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