1.1 --- a/README.txt Tue May 29 23:12:58 2018 +0200
1.2 +++ b/README.txt Tue May 29 23:50:25 2018 +0200
1.3 @@ -4,7 +4,15 @@
1.4 Landfall is a distribution of components for the L4 Runtime Environment (L4Re)
1.5 providing device support and examples for peripherals and hardware features of
1.6 various computing devices, initially supporting the Ben NanoNote and Letux 400
1.7 -notebook computers.
1.8 +notebook computers, with additional support directed at the MIPS Creator CI20.
1.9 +
1.10 +http://en.qi-hardware.com/wiki/Ben_NanoNote
1.11 +http://projects.goldelico.com/p/letux400/
1.12 +https://www.elinux.org/MIPS_Creator_CI20
1.13 +
1.14 +It builds on work done to make L4Re available on these platforms, itself
1.15 +building on work by others to port L4Re and Fiasco.OC to the MIPS
1.16 +architecture.
1.17
1.18 Getting Started
1.19 ===============
1.20 @@ -26,21 +34,29 @@
1.21 configuring and building the software. Building can be done after the steps
1.22 described below.
1.23
1.24 +Some dependencies are also needed and these are documented in a section below.
1.25 +To actually build the software, various development tools are required, and
1.26 +suggestions are also provided in the dependencies section.
1.27 +
1.28 Configuring this Software
1.29 -------------------------
1.30
1.31 Some files may need to be adjusted for the device on which the software is to
1.32 be deployed. A script is provided to check and update them:
1.33
1.34 -$LANDFALL/tools/checkconfig.sh
1.35 +$LANDFALL/tools/checkconfig.sh $PLATFORM
1.36
1.37 -(Here, $LANDFALL needs to expand to the location of this distribution.)
1.38 +(Here, $LANDFALL needs to expand to the location of this distribution whereas
1.39 +$PLATFORM indicates a platform type.)
1.40
1.41 For example:
1.42
1.43 -$LANDFALL/tools/checkconfig.sh qi_lb60
1.44 +~/L4/Landfall/tools/checkconfig.sh qi_lb60
1.45
1.46 -This configures the files for the Ben NanoNote.
1.47 +This configures the files for the Ben NanoNote. See the following file for a
1.48 +list of supported platforms:
1.49 +
1.50 +conf/landfall-examples/platforms.txt
1.51
1.52 Installing this Software
1.53 ------------------------
1.54 @@ -60,31 +76,52 @@
1.55 (The repository root of the L4Re/Fiasco.OC distribution typically has a
1.56 directory name of "src".)
1.57
1.58 +Building the Software
1.59 +---------------------
1.60 +
1.61 With this software installed into the appropriate location, the instructions
1.62 -for building Fiasco.OC and L4Re can now be followed. This process should
1.63 -proceed without error.
1.64 +for building Fiasco.OC and L4Re can now be followed. (They are provided in the
1.65 +L4Re-Fiasco.OC-patches distribution.) This process should proceed without
1.66 +error.
1.67
1.68 As a consequence of building Fiasco.OC and L4Re, a payload can be generated
1.69 and deployed for one of the examples provided by this software distribution.
1.70 For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
1.71 distribution, the following commands might be run:
1.72
1.73 +mkdir mybuild/images
1.74 cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
1.75 make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
1.76
1.77 -First, a module list is copied from the conf/landfall-examples directory to
1.78 +First, a directory for images or payloads is created. Here, it is assumed that
1.79 +the mybuild directory has been named for building L4Re.
1.80 +
1.81 +Then, a module list is copied from the conf/landfall-examples directory to
1.82 conf/modules.list, this being the place where the build system obtains the
1.83 details of the software to include in the payload.
1.84
1.85 -Then, the make invocation combines programs and libraries found in the mybuild
1.86 -directory and uses the indicated payload to construct, in this case, an
1.87 -example demonstrating use of the Ben NanoNote's keypad.
1.88 +Finally, the make invocation combines programs and libraries found in the
1.89 +mybuild directory and uses the indicated payload to construct, in this case,
1.90 +an example demonstrating use of the Ben NanoNote's keypad.
1.91 +
1.92 +Deploying the Software
1.93 +----------------------
1.94 +
1.95 +The resulting payload should reside in the created images directory and be
1.96 +deployed to the appropriate location on storage media used to boot the target
1.97 +device. For the above example, the following payload would be created:
1.98 +
1.99 +mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage
1.100 +
1.101 +More information about deploying payloads and booting devices is provided in
1.102 +the L4Re-Fiasco.OC-patches distribution's documentation.
1.103
1.104 Source Code Overview
1.105 ====================
1.106
1.107 -This distribution provides packages for use within L4Re, located in the
1.108 -src/l4/pkg directory. They are currently as follows:
1.109 +This distribution provides packages for use within L4Re, located in the pkg
1.110 +directory in this distribution and in the src/l4/pkg directory within the L4Re
1.111 +repository structure. They are currently as follows:
1.112
1.113 devices - a collection of device drivers and libraries
1.114 landfall-examples - a collection of examples demonstrating the devices
1.115 @@ -118,24 +155,29 @@
1.116 provide abstractions for working with peripherals defined at the hardware
1.117 level. It is envisaged that each peripheral-specific library will eventually
1.118 have corresponding server support, at least where this would offer a
1.119 -reasonable kind of abstraction. (Some kinds of peripherals may only be
1.120 -accessed when providing a device with different outward characteristics to
1.121 -those exposed at the hardware level.)
1.122 +reasonable kind of abstraction.
1.123 +
1.124 +(Some kinds of peripherals may, in fact, only be accessed when providing a
1.125 +device with different outward characteristics to those exposed at the hardware
1.126 +level. Other aspects of the hardware are also best maintained as libraries or
1.127 +data for use by other components, such as information about display panels.
1.128 +Such things do not need their own server whose only purpose would be to
1.129 +provide static data to other programs, and even then only very occasionally.)
1.130
1.131 System Architecture
1.132 -------------------
1.133
1.134 A significant motivation for providing server programs is to isolate
1.135 device-specific operations within separate components, thus preventing each
1.136 -component from having too broad access to low-level system functionality,
1.137 -whilst also encouraging the combination of components to achieve configuration
1.138 +component from having too broad access to low-level system functionality. The
1.139 +combination of components is then encouraged to achieve configuration
1.140 objectives.
1.141
1.142 For example, two computing systems that employ the same LCD controller might
1.143 each employ different screen types and have different ways of controlling
1.144 display behaviour. By defining explicit mechanisms for combining access to
1.145 these different aspects of the hardware, common elements (such as the LCD
1.146 -controller) may be supported by a device server that can be reused, with
1.147 +controller) may be encapsulated by a device server that can be reused, with
1.148 differing elements (such as the screen type) being described by separate
1.149 resources or components that can be introduced as required.
1.150
1.151 @@ -158,23 +200,37 @@
1.152
1.153 Here, the CPM device provides access to the clock and power management
1.154 functionality, the display device provides access to the backlight and is
1.155 -responsible for configuring pins for the display. Panel information is
1.156 -provided via a dynamically-loaded library.
1.157 +responsible for configuring pins for the display. Device servers are connected
1.158 +using capabilities (object references).
1.159 +
1.160 +Meanwhile, panel information is provided via a dynamically-loaded library:
1.161 +
1.162 + fb-drv <- mips-jz4740-panel.txt Library details
1.163 + \-> ... Library with panel data
1.164 +
1.165 +By providing well-defined interfacing mechanisms, the behaviour of driver code
1.166 +can be parameterised using external components, and a proliferation of
1.167 +specially-constructed device drivers is hopefully avoided.
1.168
1.169 Potential Improvements
1.170 ----------------------
1.171
1.172 Some device servers could offer a broader range of operations and there could
1.173 -be increased consistency between different implementations. For example, CPM
1.174 -servers only support operations necessary for LCD peripheral configuration.
1.175 +be increased consistency between implementations for different computing
1.176 +devices. For example, CPM servers only support operations necessary for LCD
1.177 +peripheral configuration.
1.178
1.179 Additional device servers could be provided for peripherals already supported
1.180 by libraries. For example, GPIO functionality is currently not exposed via a
1.181 -server.
1.182 +server. (L4Re's Io server seeks to support GPIO functionality in such a
1.183 +fashion.)
1.184
1.185 Panel details are provided by libraries containing the structure definitions
1.186 required by the LCD device code. These libraries may eventually be replaced by
1.187 -simple resource data files.
1.188 +simple resource data files, but it is convenient to be able to use definitions
1.189 +found in header files and to take advantage of structure definitions by just
1.190 +encoding such details in source code and then turning such code into a
1.191 +library.
1.192
1.193 Framebuffer device servers are not currently used, since fb-drv effectively
1.194 offers the desired functionality together with other things.
1.195 @@ -188,6 +244,30 @@
1.196
1.197 Plenty of other hardware support should be introduced.
1.198
1.199 +Dependencies/Prerequisites
1.200 +==========================
1.201 +
1.202 +Landfall has the following general dependencies or prerequisites:
1.203 +
1.204 +Prerequisite Suggestions
1.205 +------------ -----------
1.206 +
1.207 +Basic development tools Debian package: build-essential
1.208 +(for building the software)
1.209 +
1.210 +Cross-toolchains Buildroot C/C++ toolchains
1.211 +(for building the software) https://buildroot.org/
1.212 + or Debian toolchains (for the CI20)
1.213 +
1.214 +GNU Unifont Tested with Debian version 1:5.1.20080914-1.3
1.215 +(needed to display text) http://unifoundry.com/unifont.html
1.216 +
1.217 +Python Tested with Debian version 2.7.3-4+deb7u1
1.218 +(needed to run tools) https://www.python.org/
1.219 +
1.220 +See also the prerequisites for the L4Re-Fiasco.OC-patches distribution,
1.221 +described in that distribution's documentation.
1.222 +
1.223 Copyright and Licence Information
1.224 =================================
1.225