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 Tools and Utilities
254 ===================
255
256 The tools directory contains a number of programs useful when developing this
257 software:
258
259 checkconfig.sh - initialises files used to control run-time linking for the
260 configured device
261
262 install.sh - installs the software in a L4Re source distribution
263
264 listlibs.sh - lists library modules for inclusion in .list files
265
266 makecontrol.sh - updates the Control file for a package directory with
267 details of the provided "virtual" packages employed by the
268 build system for dependency resolution
269
270 makefonts.sh - generate binary font files from source data
271
272 readfont.py - convert GNU Unifont source files to binary form
273
274 Identifying Library Modules
275 ---------------------------
276
277 The listlibs.sh tool is intended to inspect an existing .list file, analyse
278 executable programs mentioned in that file that have already been built, and
279 to generate a list of shared libraries needed by those executables such that
280 the .list file describes all required modules for deployment.
281
282 In the l4 subdirectory of the L4Re source distribution, the tool is run as
283 follows:
284
285 $LANDFALL/tools/listlibs.sh conf/landfall-examples/$EXAMPLE.list mybuild
286
287 (Here, $LANDFALL needs to expand to the location of this distribution whereas
288 $EXAMPLE indicates an example name.)
289
290 For example:
291
292 ~/L4/Landfall/tools/listlibs.sh \
293 conf/landfall-examples/mips-qi_lb60-keypad.list mybuild
294
295 This will output a list of modules for inclusion in the .list file. It can be
296 advisable to make this change to the .list file in the Landfall distribution
297 and to then install the file into the L4Re source distribution, potentially
298 using the install.sh script.
299
300 At this point, it is important to remember that the conf/modules.list file
301 will need updating to include these new details. For example:
302
303 cp conf/landfall-examples/mips-qi_lb60-keypad.list conf/modules.list
304
305 Finally, the command to build a payload can be run:
306
307 make O=mybuild uimage E=mips-qi_lb60-keypad-example
308
309 This should consult conf/modules.list and update the contents of the generated
310 image to include any newly-added shared libraries.
311
312 Dependencies/Prerequisites
313 ==========================
314
315 Landfall has the following general dependencies or prerequisites:
316
317 Prerequisite Suggestions
318 ------------ -----------
319
320 Basic development tools Debian package: build-essential
321 (for building the software)
322
323 Cross-toolchains Buildroot C/C++ toolchains
324 (for building the software) https://buildroot.org/
325 or Debian toolchains (for the CI20)
326
327 GNU Unifont Tested with Debian version 1:5.1.20080914-1.3
328 (needed to display text) http://unifoundry.com/unifont.html
329
330 L4Re Tested with repository version r78
331 (this work's foundation) http://l4re.org/
332
333 L4Re-Fiasco.OC-patches Tested with snapshot-20180530
334 (needed for device support) http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
335
336 Python Tested with Debian version 2.7.3-4+deb7u1
337 (needed to run tools) https://www.python.org/
338
339 See also the prerequisites for the L4Re-Fiasco.OC-patches distribution,
340 described in that distribution's documentation.
341
342 Copyright and Licence Information
343 =================================
344
345 See the following Web pages for more information about this work:
346
347 http://www.boddie.org.uk/paul/Landfall.html
348
349 The author can be contacted at the following e-mail address:
350
351 paul@boddie.org.uk
352
353 Copyright and licence information can be found in the docs directory - see
354 docs/COPYING.txt and docs/LICENCE.txt for more information.