1 Introduction
2 ============
3
4 Landfall is a distribution of components for the L4 Runtime Environment (L4Re)
5 providing device support and examples for peripherals and hardware features of
6 various computing devices, initially supporting the Ben NanoNote and Letux 400
7 notebook computers.
8
9 Getting Started
10 ===============
11
12 To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
13 source distribution:
14
15 http://l4re.org/download.html
16
17 With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
18 need to be applied. This patch distribution can be obtained from the following
19 location:
20
21 http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
22
23 The "current archive" should be obtained since the "initial archive" is merely
24 provided for historical purposes. Instructions about applying the patches are
25 provided in the distributed archive, as is a summary of the issues related to
26 configuring and building the software. Building can be done after the steps
27 described below.
28
29 Configuring this Software
30 -------------------------
31
32 Some files may need to be adjusted for the device on which the software is to
33 be deployed. A script is provided to check and update them:
34
35 $LANDFALL/tools/checkconfig.sh
36
37 (Here, $LANDFALL needs to expand to the location of this distribution.)
38
39 For example:
40
41 $LANDFALL/tools/checkconfig.sh qi_lb60
42
43 This configures the files for the Ben NanoNote.
44
45 Installing this Software
46 ------------------------
47
48 With the above patches applied, this software can be installed within the
49 unpacked L4Re/Fiasco.OC distribution using a command of the following form:
50
51 $LANDFALL/tools/install.sh $L4DIR
52
53 (Here, $LANDFALL needs to expand to the location of this distribution whereas
54 $L4DIR needs to expand to the location of the L4Re/Fiasco.OC software.)
55
56 For example:
57
58 ~/L4/Landfall/tools/install.sh ~/L4/src
59
60 (The repository root of the L4Re/Fiasco.OC distribution typically has a
61 directory name of "src".)
62
63 With this software installed into the appropriate location, the instructions
64 for building Fiasco.OC and L4Re can now be followed. This process should
65 proceed without error.
66
67 As a consequence of building Fiasco.OC and L4Re, a payload can be generated
68 and deployed for one of the examples provided by this software distribution.
69 For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
70 distribution, the following commands might be run:
71
72 cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
73 make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
74
75 First, a module list is copied from the conf/landfall-examples directory to
76 conf/modules.list, this being the place where the build system obtains the
77 details of the software to include in the payload.
78
79 Then, the make invocation combines programs and libraries found in the mybuild
80 directory and uses the indicated payload to construct, in this case, an
81 example demonstrating use of the Ben NanoNote's keypad.
82
83 Source Code Overview
84 ====================
85
86 This distribution provides packages for use within L4Re, located in the
87 src/l4/pkg directory. They are currently as follows:
88
89 devices - a collection of device drivers and libraries
90 landfall-examples - a collection of examples demonstrating the devices
91
92 In addition to the above, configuration files are provided for the example
93 programs in the conf/landfall-examples directory.
94
95 Device Support
96 ==============
97
98 A selection of devices are supported by this software. They are found within
99 the pkg/devices directory and are currently the following:
100
101 backlight - display backlight control
102 cpm - clock and power management
103 display - device-specific display control
104 fb - framebuffer access
105 input - input event delivery
106 keypad - keypad/keyboard scanning
107 lcd - LCD and other display peripheral support
108 pwm - pulse width modulation support
109 spi - serial peripheral interface support
110
111 Many device types provide the following kinds of support:
112
113 * Server programs that regulate access to devices
114 * Client libraries that provide access to the server programs
115 * General library support for server programs to use
116
117 In addition to the above, more general libraries found in the lib subdirectory
118 provide abstractions for working with peripherals defined at the hardware
119 level. It is envisaged that each peripheral-specific library will eventually
120 have corresponding server support, at least where this would offer a
121 reasonable kind of abstraction. (Some kinds of peripherals may only be
122 accessed when providing a device with different outward characteristics to
123 those exposed at the hardware level.)
124
125 System Architecture
126 -------------------
127
128 A significant motivation for providing server programs is to isolate
129 device-specific operations within separate components, thus preventing each
130 component from having too broad access to low-level system functionality,
131 whilst also encouraging the combination of components to achieve configuration
132 objectives.
133
134 For example, two computing systems that employ the same LCD controller might
135 each employ different screen types and have different ways of controlling
136 display behaviour. By defining explicit mechanisms for combining access to
137 these different aspects of the hardware, common elements (such as the LCD
138 controller) may be supported by a device server that can be reused, with
139 differing elements (such as the screen type) being described by separate
140 resources or components that can be introduced as required.
141
142 Here is how the Ben NanoNote's framebuffer is supported by components:
143
144 fb-drv (*) -> dev_cpm_jz4740 Clock configuration
145 \-> dev_display_qi_lb60 Display control
146 \-> dev_backlight_spi_ili8960 Backlight control
147 \-> dev_spi_jz4740 Backlight communication
148
149 And here is how the Letux 400's framebuffer is supported:
150
151 fb-drv (*) -> dev_cpm_jz4730 Clock configuration
152 \-> dev_display_letux400 Display control
153 \-> dev_backlight_pwm Backlight control
154 \-> dev_pwm_jz4730 Backlight communication
155
156 (*) fb-drv links to the same generic JZ4740 LCD controller library in both
157 cases
158
159 Here, the CPM device provides access to the clock and power management
160 functionality, the display device provides access to the backlight and is
161 responsible for configuring pins for the display. Panel information is
162 provided via a dynamically-loaded library.
163
164 Potential Improvements
165 ----------------------
166
167 Some device servers could offer a broader range of operations and there could
168 be increased consistency between different implementations. For example, CPM
169 servers only support operations necessary for LCD peripheral configuration.
170
171 Additional device servers could be provided for peripherals already supported
172 by libraries. For example, GPIO functionality is currently not exposed via a
173 server.
174
175 Panel details are provided by libraries containing the structure definitions
176 required by the LCD device code. These libraries may eventually be replaced by
177 simple resource data files.
178
179 Framebuffer device servers are not currently used, since fb-drv effectively
180 offers the desired functionality together with other things.
181
182 The input event device support needs to be made properly interoperable with
183 the L4Re event framework so that existing software can be supplied with keypad
184 events.
185
186 Keypad device support should support interrupt handling to allow the scanning
187 activity to sleep when no activity is taking place.
188
189 Plenty of other hardware support should be introduced.
190
191 Copyright and Licence Information
192 =================================
193
194 See the following Web pages for more information about this work:
195
196 http://www.boddie.org.uk/paul/Landfall.html
197
198 The author can be contacted at the following e-mail address:
199
200 paul@boddie.org.uk
201
202 Copyright and licence information can be found in the docs directory - see
203 docs/COPYING.txt and docs/LICENCE.txt for more information.