1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/README.txt Fri May 25 23:59:55 2018 +0200
1.3 @@ -0,0 +1,190 @@
1.4 +Introduction
1.5 +============
1.6 +
1.7 +Landfall is a distribution of components for the L4 Runtime Environment (L4Re)
1.8 +providing device support and examples for peripherals and hardware features of
1.9 +various computing devices, initially supporting the Ben NanoNote and Letux 400
1.10 +notebook computers.
1.11 +
1.12 +Getting Started
1.13 +===============
1.14 +
1.15 +To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
1.16 +source distribution:
1.17 +
1.18 +http://l4re.org/download.html
1.19 +
1.20 +With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
1.21 +need to be applied. This patch distribution can be obtained from the following
1.22 +location:
1.23 +
1.24 +http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
1.25 +
1.26 +The "current archive" should be obtained since the "initial archive" is merely
1.27 +provided for historical purposes. Instructions about applying the patches are
1.28 +provided in the distributed archive, as is a summary of the issues related to
1.29 +configuring and building the software. Building can be done after the steps
1.30 +described below.
1.31 +
1.32 +Installing this Software
1.33 +------------------------
1.34 +
1.35 +With the above patches applied, this software can be installed within the
1.36 +unpacked L4Re/Fiasco.OC distribution using a command of the following form:
1.37 +
1.38 +$LANDFALL/tools/install.sh $L4DIR
1.39 +
1.40 +(Here, $LANDFALL needs to expand to the location of this distribution whereas
1.41 +$L4DIR needs to expand to the location of the L4Re/Fiasco.OC software.)
1.42 +
1.43 +For example:
1.44 +
1.45 +~/L4/Landfall/tools/install.sh ~/L4/src
1.46 +
1.47 +(The repository root of the L4Re/Fiasco.OC distribution typically has a
1.48 +directory name of "src".)
1.49 +
1.50 +With this software installed into the appropriate location, the instructions
1.51 +for building Fiasco.OC and L4Re can now be followed. This process should
1.52 +proceed without error.
1.53 +
1.54 +As a consequence of building Fiasco.OC and L4Re, a payload can be generated
1.55 +and deployed for one of the examples provided by this software distribution.
1.56 +For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
1.57 +distribution, the following commands might be run:
1.58 +
1.59 +cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
1.60 +make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
1.61 +
1.62 +First, a module list is copied from the conf/landfall-examples directory to
1.63 +conf/modules.list, this being the place where the build system obtains the
1.64 +details of the software to include in the payload.
1.65 +
1.66 +Then, the make invocation combines programs and libraries found in the mybuild
1.67 +directory and uses the indicated payload to construct, in this case, an
1.68 +example demonstrating use of the Ben NanoNote's keypad.
1.69 +
1.70 +Source Code Overview
1.71 +====================
1.72 +
1.73 +This distribution provides packages for use within L4Re, located in the
1.74 +src/l4/pkg directory. They are currently as follows:
1.75 +
1.76 + devices - a collection of device drivers and libraries
1.77 + landfall-examples - a collection of examples demonstrating the devices
1.78 +
1.79 +In addition to the above, configuration files are provided for the example
1.80 +programs in the conf/landfall-examples directory.
1.81 +
1.82 +Device Support
1.83 +==============
1.84 +
1.85 +A selection of devices are supported by this software. They are found within
1.86 +the pkg/devices directory and are currently the following:
1.87 +
1.88 + backlight - display backlight control
1.89 + cpm - clock and power management
1.90 + display - device-specific display control
1.91 + fb - framebuffer access
1.92 + input - input event delivery
1.93 + keypad - keypad/keyboard scanning
1.94 + lcd - LCD and other display peripheral support
1.95 + panel - device-specific panel definitions
1.96 + pwm - pulse width modulation support
1.97 + spi - serial peripheral interface support
1.98 +
1.99 +Many device types provide the following kinds of support:
1.100 +
1.101 + * Server programs that regulate access to devices
1.102 + * Client libraries that provide access to the server programs
1.103 + * General library support for server programs to use
1.104 +
1.105 +In addition to the above, more general libraries found in the lib subdirectory
1.106 +provide abstractions for working with peripherals defined at the hardware
1.107 +level. It is envisaged that each peripheral-specific library will eventually
1.108 +have corresponding server support, at least where this would offer a
1.109 +reasonable kind of abstraction. (Some kinds of peripherals may only be
1.110 +accessed when providing a device with different outward characteristics to
1.111 +those exposed at the hardware level.)
1.112 +
1.113 +System Architecture
1.114 +-------------------
1.115 +
1.116 +A significant motivation for providing server programs is to isolate
1.117 +device-specific operations within separate components, thus preventing each
1.118 +component from having too broad access to low-level system functionality,
1.119 +whilst also encouraging the combination of components to achieve configuration
1.120 +objectives.
1.121 +
1.122 +For example, two computing systems that employ the same LCD controller might
1.123 +each employ different screen types and have different ways of controlling
1.124 +display behaviour. By defining explicit mechanisms for combining access to
1.125 +these different aspects of the hardware, common elements (such as the LCD
1.126 +controller) may be supported by a device server that can be reused, with
1.127 +differing elements (such as the screen type) being described by separate
1.128 +resources or components that can be introduced as required.
1.129 +
1.130 +Here is how the Ben NanoNote's framebuffer is supported by components:
1.131 +
1.132 + fb-drv (*) -> dev_cpm_jz4740 Clock configuration
1.133 + \-> dev_display_qi_lb60 Display control
1.134 + \-> dev_backlight_spi_ili8960 Backlight control
1.135 + \-> dev_spi_jz4740 Backlight communication
1.136 + \-> dev_panel_qi_lb60 Panel information
1.137 +
1.138 +And here is how the Letux 400's framebuffer is supported:
1.139 +
1.140 + fb-drv (*) -> dev_cpm_jz4730 Clock configuration
1.141 + \-> dev_display_letux400 Display control
1.142 + \-> dev_backlight_pwm Backlight control
1.143 + \-> dev_pwm_jz4730 Backlight communication
1.144 + \-> dev_panel_letux400 Panel information
1.145 +
1.146 +(*) fb-drv links to the same generic JZ4740 LCD controller library in both
1.147 + cases
1.148 +
1.149 +Here, the CPM device provides access to the clock and power management
1.150 +functionality, the display device provides access to the backlight and is
1.151 +responsible for configuring pins for the display, and the panel device
1.152 +provides information about the screen that the LCD controller needs.
1.153 +
1.154 +Potential Improvements
1.155 +----------------------
1.156 +
1.157 +Some device servers could offer a broader range of operations and there could
1.158 +be increased consistency between different implementations. For example, CPM
1.159 +servers only support operations necessary for LCD peripheral configuration.
1.160 +
1.161 +Additional device servers could be provided for peripherals already supported
1.162 +by libraries. For example, GPIO functionality is currently not exposed via a
1.163 +server.
1.164 +
1.165 +Panel device servers may eventually be replaced by simple resources given that
1.166 +their only job is to provide precomputed data via a capability channel. This
1.167 +could be done using a file bundled with the payload.
1.168 +
1.169 +Framebuffer device servers are not currently used, since fb-drv effectively
1.170 +offers the desired functionality together with other things.
1.171 +
1.172 +The input event device support needs to be made properly interoperable with
1.173 +the L4Re event framework so that existing software can be supplied with keypad
1.174 +events.
1.175 +
1.176 +Keypad device support should support interrupt handling to allow the scanning
1.177 +activity to sleep when no activity is taking place.
1.178 +
1.179 +Plenty of other hardware support should be introduced.
1.180 +
1.181 +Copyright and Licence Information
1.182 +=================================
1.183 +
1.184 +See the following Web pages for more information about this work:
1.185 +
1.186 +http://www.boddie.org.uk/paul/Landfall.html
1.187 +
1.188 +The author can be contacted at the following e-mail address:
1.189 +
1.190 +paul@boddie.org.uk
1.191 +
1.192 +Copyright and licence information can be found in the docs directory - see
1.193 +docs/COPYING.txt and docs/LICENCE.txt for more information.