# HG changeset patch # User Paul Boddie # Date 1527630625 -7200 # Node ID 88059eabab6d417993ef814427383927519a66a4 # Parent 8d44aeecd9c54971afa560f60a5a6c5b72fc8bac Extended the documentation generally, also adding a section on dependencies. diff -r 8d44aeecd9c5 -r 88059eabab6d README.txt --- a/README.txt Tue May 29 23:12:58 2018 +0200 +++ b/README.txt Tue May 29 23:50:25 2018 +0200 @@ -4,7 +4,15 @@ Landfall is a distribution of components for the L4 Runtime Environment (L4Re) providing device support and examples for peripherals and hardware features of various computing devices, initially supporting the Ben NanoNote and Letux 400 -notebook computers. +notebook computers, with additional support directed at the MIPS Creator CI20. + +http://en.qi-hardware.com/wiki/Ben_NanoNote +http://projects.goldelico.com/p/letux400/ +https://www.elinux.org/MIPS_Creator_CI20 + +It builds on work done to make L4Re available on these platforms, itself +building on work by others to port L4Re and Fiasco.OC to the MIPS +architecture. Getting Started =============== @@ -26,21 +34,29 @@ configuring and building the software. Building can be done after the steps described below. +Some dependencies are also needed and these are documented in a section below. +To actually build the software, various development tools are required, and +suggestions are also provided in the dependencies section. + Configuring this Software ------------------------- Some files may need to be adjusted for the device on which the software is to be deployed. A script is provided to check and update them: -$LANDFALL/tools/checkconfig.sh +$LANDFALL/tools/checkconfig.sh $PLATFORM -(Here, $LANDFALL needs to expand to the location of this distribution.) +(Here, $LANDFALL needs to expand to the location of this distribution whereas +$PLATFORM indicates a platform type.) For example: -$LANDFALL/tools/checkconfig.sh qi_lb60 +~/L4/Landfall/tools/checkconfig.sh qi_lb60 -This configures the files for the Ben NanoNote. +This configures the files for the Ben NanoNote. See the following file for a +list of supported platforms: + +conf/landfall-examples/platforms.txt Installing this Software ------------------------ @@ -60,31 +76,52 @@ (The repository root of the L4Re/Fiasco.OC distribution typically has a directory name of "src".) +Building the Software +--------------------- + With this software installed into the appropriate location, the instructions -for building Fiasco.OC and L4Re can now be followed. This process should -proceed without error. +for building Fiasco.OC and L4Re can now be followed. (They are provided in the +L4Re-Fiasco.OC-patches distribution.) This process should proceed without +error. As a consequence of building Fiasco.OC and L4Re, a payload can be generated and deployed for one of the examples provided by this software distribution. For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC distribution, the following commands might be run: +mkdir mybuild/images cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example -First, a module list is copied from the conf/landfall-examples directory to +First, a directory for images or payloads is created. Here, it is assumed that +the mybuild directory has been named for building L4Re. + +Then, a module list is copied from the conf/landfall-examples directory to conf/modules.list, this being the place where the build system obtains the details of the software to include in the payload. -Then, the make invocation combines programs and libraries found in the mybuild -directory and uses the indicated payload to construct, in this case, an -example demonstrating use of the Ben NanoNote's keypad. +Finally, the make invocation combines programs and libraries found in the +mybuild directory and uses the indicated payload to construct, in this case, +an example demonstrating use of the Ben NanoNote's keypad. + +Deploying the Software +---------------------- + +The resulting payload should reside in the created images directory and be +deployed to the appropriate location on storage media used to boot the target +device. For the above example, the following payload would be created: + +mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage + +More information about deploying payloads and booting devices is provided in +the L4Re-Fiasco.OC-patches distribution's documentation. Source Code Overview ==================== -This distribution provides packages for use within L4Re, located in the -src/l4/pkg directory. They are currently as follows: +This distribution provides packages for use within L4Re, located in the pkg +directory in this distribution and in the src/l4/pkg directory within the L4Re +repository structure. They are currently as follows: devices - a collection of device drivers and libraries landfall-examples - a collection of examples demonstrating the devices @@ -118,24 +155,29 @@ provide abstractions for working with peripherals defined at the hardware level. It is envisaged that each peripheral-specific library will eventually have corresponding server support, at least where this would offer a -reasonable kind of abstraction. (Some kinds of peripherals may only be -accessed when providing a device with different outward characteristics to -those exposed at the hardware level.) +reasonable kind of abstraction. + +(Some kinds of peripherals may, in fact, only be accessed when providing a +device with different outward characteristics to those exposed at the hardware +level. Other aspects of the hardware are also best maintained as libraries or +data for use by other components, such as information about display panels. +Such things do not need their own server whose only purpose would be to +provide static data to other programs, and even then only very occasionally.) System Architecture ------------------- A significant motivation for providing server programs is to isolate device-specific operations within separate components, thus preventing each -component from having too broad access to low-level system functionality, -whilst also encouraging the combination of components to achieve configuration +component from having too broad access to low-level system functionality. The +combination of components is then encouraged to achieve configuration objectives. For example, two computing systems that employ the same LCD controller might each employ different screen types and have different ways of controlling display behaviour. By defining explicit mechanisms for combining access to these different aspects of the hardware, common elements (such as the LCD -controller) may be supported by a device server that can be reused, with +controller) may be encapsulated by a device server that can be reused, with differing elements (such as the screen type) being described by separate resources or components that can be introduced as required. @@ -158,23 +200,37 @@ Here, the CPM device provides access to the clock and power management functionality, the display device provides access to the backlight and is -responsible for configuring pins for the display. Panel information is -provided via a dynamically-loaded library. +responsible for configuring pins for the display. Device servers are connected +using capabilities (object references). + +Meanwhile, panel information is provided via a dynamically-loaded library: + + fb-drv <- mips-jz4740-panel.txt Library details + \-> ... Library with panel data + +By providing well-defined interfacing mechanisms, the behaviour of driver code +can be parameterised using external components, and a proliferation of +specially-constructed device drivers is hopefully avoided. Potential Improvements ---------------------- Some device servers could offer a broader range of operations and there could -be increased consistency between different implementations. For example, CPM -servers only support operations necessary for LCD peripheral configuration. +be increased consistency between implementations for different computing +devices. For example, CPM servers only support operations necessary for LCD +peripheral configuration. Additional device servers could be provided for peripherals already supported by libraries. For example, GPIO functionality is currently not exposed via a -server. +server. (L4Re's Io server seeks to support GPIO functionality in such a +fashion.) Panel details are provided by libraries containing the structure definitions required by the LCD device code. These libraries may eventually be replaced by -simple resource data files. +simple resource data files, but it is convenient to be able to use definitions +found in header files and to take advantage of structure definitions by just +encoding such details in source code and then turning such code into a +library. Framebuffer device servers are not currently used, since fb-drv effectively offers the desired functionality together with other things. @@ -188,6 +244,30 @@ Plenty of other hardware support should be introduced. +Dependencies/Prerequisites +========================== + +Landfall has the following general dependencies or prerequisites: + +Prerequisite Suggestions +------------ ----------- + +Basic development tools Debian package: build-essential +(for building the software) + +Cross-toolchains Buildroot C/C++ toolchains +(for building the software) https://buildroot.org/ + or Debian toolchains (for the CI20) + +GNU Unifont Tested with Debian version 1:5.1.20080914-1.3 +(needed to display text) http://unifoundry.com/unifont.html + +Python Tested with Debian version 2.7.3-4+deb7u1 +(needed to run tools) https://www.python.org/ + +See also the prerequisites for the L4Re-Fiasco.OC-patches distribution, +described in that distribution's documentation. + Copyright and Licence Information =================================