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