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