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