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, with additional support directed at the MIPS Creator CI20.
8
9 http://en.qi-hardware.com/wiki/Ben_NanoNote
10 http://projects.goldelico.com/p/letux400/
11 https://www.elinux.org/MIPS_Creator_CI20
12
13 It builds on work done to make L4Re available on these platforms, itself
14 building on work by others to port L4Re and Fiasco.OC to the MIPS
15 architecture.
16
17 Getting Started
18 ===============
19
20 To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
21 source distribution:
22
23 http://l4re.org/download.html
24
25 With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
26 need to be applied. This patch distribution can be obtained from the following
27 location:
28
29 http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
30
31 The "current archive" should be obtained since the "initial archive" is merely
32 provided for historical purposes. Instructions about applying the patches are
33 provided in the distributed archive, as is a summary of the issues related to
34 configuring and building the software. Building can be done after the steps
35 described below.
36
37 Some dependencies are also needed and these are documented in a section below.
38 To actually build the software, various development tools are required, and
39 suggestions are also provided in the dependencies section.
40
41 Configuring this Software
42 -------------------------
43
44 Some files may need to be adjusted for the device on which the software is to
45 be deployed. A script is provided to check and update them:
46
47 $LANDFALL/tools/checkconfig.sh $PLATFORM
48
49 (Here, $LANDFALL needs to expand to the location of this distribution whereas
50 $PLATFORM indicates a platform type.)
51
52 For example:
53
54 ~/L4/Landfall/tools/checkconfig.sh qi_lb60
55
56 This configures the files for the Ben NanoNote. See the following file for a
57 list of supported platforms:
58
59 conf/landfall-examples/platforms.txt
60
61 Installing this Software
62 ------------------------
63
64 With the above patches applied, this software can be installed within the
65 unpacked L4Re/Fiasco.OC distribution using a command of the following form:
66
67 $LANDFALL/tools/install.sh $L4DIR
68
69 (Here, $LANDFALL needs to expand to the location of this distribution whereas
70 $L4DIR needs to expand to the location of the L4Re/Fiasco.OC software.)
71
72 For example:
73
74 ~/L4/Landfall/tools/install.sh ~/L4/src
75
76 (The repository root of the L4Re/Fiasco.OC distribution typically has a
77 directory name of "src".)
78
79 Building the Software
80 ---------------------
81
82 With this software installed into the appropriate location, the instructions
83 for building Fiasco.OC and L4Re can now be followed. (They are provided in the
84 L4Re-Fiasco.OC-patches distribution.) This process should proceed without
85 error.
86
87 As a consequence of building Fiasco.OC and L4Re, a payload can be generated
88 and deployed for one of the examples provided by this software distribution.
89 For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
90 distribution, the following commands might be run:
91
92 mkdir mybuild/images
93 cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
94 make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
95
96 First, a directory for images or payloads is created. Here, it is assumed that
97 the mybuild directory has been named for building L4Re.
98
99 Then, a module list is copied from the conf/landfall-examples directory to
100 conf/modules.list, this being the place where the build system obtains the
101 details of the software to include in the payload.
102
103 Finally, the make invocation combines programs and libraries found in the
104 mybuild directory and uses the indicated payload to construct, in this case,
105 an example demonstrating use of the Ben NanoNote's keypad.
106
107 Deploying the Software
108 ----------------------
109
110 The resulting payload should reside in the created images directory and be
111 deployed to the appropriate location on storage media used to boot the target
112 device. For the above example, the following payload would be created:
113
114 mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage
115
116 More information about deploying payloads and booting devices is provided in
117 the L4Re-Fiasco.OC-patches distribution's documentation.
118
119 Source Code Overview
120 ====================
121
122 This distribution provides packages for use within L4Re, located in the pkg
123 directory in this distribution and in the src/l4/pkg directory within the L4Re
124 repository structure. They are currently as follows:
125
126 devices - a collection of device drivers and libraries
127 landfall-examples - a collection of examples demonstrating the devices
128
129 In addition to the above, configuration files are provided for the example
130 programs in the conf/landfall-examples directory.
131
132 Device Support
133 ==============
134
135 A selection of devices are supported by this software. They are found within
136 the pkg/devices directory and are currently the following:
137
138 backlight - display backlight control
139 cpm - clock and power management
140 display - device-specific display control
141 fb - framebuffer access
142 input - input event delivery
143 keypad - keypad/keyboard scanning
144 lcd - LCD and other display peripheral support
145 pwm - pulse width modulation support
146 spi - serial peripheral interface support
147
148 Many device types provide the following kinds of support:
149
150 * Server programs that regulate access to devices
151 * Client libraries that provide access to the server programs
152 * General library support for server programs to use
153
154 In addition to the above, more general libraries found in the lib subdirectory
155 provide abstractions for working with peripherals defined at the hardware
156 level. It is envisaged that each peripheral-specific library will eventually
157 have corresponding server support, at least where this would offer a
158 reasonable kind of abstraction.
159
160 (Some kinds of peripherals may, in fact, only be accessed when providing a
161 device with different outward characteristics to those exposed at the hardware
162 level. Other aspects of the hardware are also best maintained as libraries or
163 data for use by other components, such as information about display panels.
164 Such things do not need their own server whose only purpose would be to
165 provide static data to other programs, and even then only very occasionally.)
166
167 System Architecture
168 -------------------
169
170 A significant motivation for providing server programs is to isolate
171 device-specific operations within separate components, thus preventing each
172 component from having too broad access to low-level system functionality. The
173 combination of components is then encouraged to achieve configuration
174 objectives.
175
176 For example, two computing systems that employ the same LCD controller might
177 each employ different screen types and have different ways of controlling
178 display behaviour. By defining explicit mechanisms for combining access to
179 these different aspects of the hardware, common elements (such as the LCD
180 controller) may be encapsulated by a device server that can be reused, with
181 differing elements (such as the screen type) being described by separate
182 resources or components that can be introduced as required.
183
184 Here is how the Ben NanoNote's framebuffer is supported by components:
185
186 fb-drv (*) -> dev_cpm_jz4740 Clock configuration
187 \-> dev_display_qi_lb60 Display control
188 \-> dev_backlight_spi_ili8960 Backlight control
189 \-> dev_spi_jz4740 Backlight communication
190
191 And here is how the Letux 400's framebuffer is supported:
192
193 fb-drv (*) -> dev_cpm_jz4730 Clock configuration
194 \-> dev_display_letux400 Display control
195 \-> dev_backlight_pwm Backlight control
196 \-> dev_pwm_jz4730 Backlight communication
197
198 (*) fb-drv links to the same generic JZ4740 LCD controller library in both
199 cases
200
201 Here, the CPM device provides access to the clock and power management
202 functionality, the display device provides access to the backlight and is
203 responsible for configuring pins for the display. Device servers are connected
204 using capabilities (object references).
205
206 Meanwhile, panel information is provided via a dynamically-loaded library:
207
208 fb-drv <- mips-jz4740-panel.txt Library details
209 \-> ... Library with panel data
210
211 This method of obtaining a configured library name in order to load it
212 dynamically is effectively equivalent to having a symbolic link identifying
213 the library referencing the desired, specific library to be used. Since the
214 "rom" virtual filesystem does not appear to support symbolic links, this
215 method is used instead.
216
217 By providing well-defined interfacing mechanisms, the behaviour of driver code
218 can be parameterised using external components, and a proliferation of
219 specially-constructed device drivers is hopefully avoided.
220
221 Potential Improvements
222 ----------------------
223
224 Some device servers could offer a broader range of operations and there could
225 be increased consistency between implementations for different computing
226 devices. For example, CPM servers only support operations necessary for LCD
227 peripheral configuration.
228
229 Additional device servers could be provided for peripherals already supported
230 by libraries. For example, GPIO functionality is currently not exposed via a
231 server. (L4Re's Io server seeks to support GPIO functionality in such a
232 fashion.)
233
234 Panel details are provided by libraries containing the structure definitions
235 required by the LCD device code. These libraries may eventually be replaced by
236 simple resource data files, but it is convenient to be able to use definitions
237 found in header files and to take advantage of structure definitions by just
238 encoding such details in source code and then turning such code into a
239 library.
240
241 Framebuffer device servers are not currently used, since fb-drv effectively
242 offers the desired functionality together with other things.
243
244 The input event device support needs to be made properly interoperable with
245 the L4Re event framework so that existing software can be supplied with keypad
246 events.
247
248 Keypad device support should support interrupt handling to allow the scanning
249 activity to sleep when no activity is taking place.
250
251 Plenty of other hardware support should be introduced.
252
253 Dependencies/Prerequisites
254 ==========================
255
256 Landfall has the following general dependencies or prerequisites:
257
258 Prerequisite Suggestions
259 ------------ -----------
260
261 Basic development tools Debian package: build-essential
262 (for building the software)
263
264 Cross-toolchains Buildroot C/C++ toolchains
265 (for building the software) https://buildroot.org/
266 or Debian toolchains (for the CI20)
267
268 GNU Unifont Tested with Debian version 1:5.1.20080914-1.3
269 (needed to display text) http://unifoundry.com/unifont.html
270
271 L4Re Tested with repository version r78
272 (this work's foundation) http://l4re.org/
273
274 L4Re-Fiasco.OC-patches Tested with snapshot-20180530
275 (needed for device support) http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
276
277 Python Tested with Debian version 2.7.3-4+deb7u1
278 (needed to run tools) https://www.python.org/
279
280 See also the prerequisites for the L4Re-Fiasco.OC-patches distribution,
281 described in that distribution's documentation.
282
283 Copyright and Licence Information
284 =================================
285
286 See the following Web pages for more information about this work:
287
288 http://www.boddie.org.uk/paul/Landfall.html
289
290 The author can be contacted at the following e-mail address:
291
292 paul@boddie.org.uk
293
294 Copyright and licence information can be found in the docs directory - see
295 docs/COPYING.txt and docs/LICENCE.txt for more information.