1.1 --- a/README.txt Wed Feb 20 15:31:14 2019 +0100
1.2 +++ b/README.txt Sat Apr 13 19:28:39 2019 +0200
1.3 @@ -6,338 +6,29 @@
1.4 various computing devices, initially supporting the Ben NanoNote and Letux 400
1.5 notebook computers, with additional support directed at the MIPS Creator CI20.
1.6
1.7 -http://en.qi-hardware.com/wiki/Ben_NanoNote
1.8 -http://projects.goldelico.com/p/letux400/
1.9 -https://www.elinux.org/MIPS_Creator_CI20
1.10 -
1.11 -It builds on work done to make L4Re available on these platforms, itself
1.12 -building on work by others to port L4Re and Fiasco.OC to the MIPS
1.13 -architecture.
1.14 -
1.15 -Getting Started
1.16 -===============
1.17 -
1.18 -To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
1.19 -source distribution:
1.20 -
1.21 -http://l4re.org/download.html
1.22 -
1.23 -With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
1.24 -need to be applied. This patch distribution can be obtained from the following
1.25 -location:
1.26 -
1.27 -http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
1.28 -
1.29 -The "current archive" should be obtained since the "initial archive" is merely
1.30 -provided for historical purposes. Instructions about applying the patches are
1.31 -provided in the distributed archive, as is a summary of the issues related to
1.32 -configuring and building the software. Building can be done after the steps
1.33 -described below.
1.34 -
1.35 -Some dependencies are also needed and these are documented in a section below.
1.36 -To actually build the software, various development tools are required, and
1.37 -suggestions are also provided in the dependencies section.
1.38 -
1.39 -Configuring this Software
1.40 --------------------------
1.41 -
1.42 -Some files may need to be adjusted for the device on which the software is to
1.43 -be deployed. A script is provided to check and update them:
1.44 -
1.45 -$LANDFALL/tools/checkconfig.sh $PLATFORM
1.46 -
1.47 -(Here, $LANDFALL needs to expand to the location of this distribution whereas
1.48 -$PLATFORM indicates a platform type.)
1.49 -
1.50 -For example:
1.51 -
1.52 -~/L4/Landfall/tools/checkconfig.sh qi_lb60
1.53 -
1.54 -This configures the files for the Ben NanoNote. See the following file for a
1.55 -list of supported platforms:
1.56 -
1.57 -conf/landfall-examples/platforms.txt
1.58 -
1.59 -Installing this Software
1.60 -------------------------
1.61 -
1.62 -With the above patches applied, this software can be installed within the
1.63 -unpacked L4Re/Fiasco.OC distribution using a command of the following form:
1.64 -
1.65 -$LANDFALL/tools/install.sh $L4DIR
1.66 -
1.67 -(Here, $LANDFALL needs to expand to the location of this distribution whereas
1.68 -$L4DIR needs to expand to the location of the L4Re/Fiasco.OC software.)
1.69 -
1.70 -For example:
1.71 -
1.72 -~/L4/Landfall/tools/install.sh ~/L4/src
1.73 -
1.74 -(The repository root of the L4Re/Fiasco.OC distribution typically has a
1.75 -directory name of "src".)
1.76 -
1.77 -Building the Software
1.78 ----------------------
1.79 -
1.80 -With this software installed into the appropriate location, the instructions
1.81 -for building Fiasco.OC and L4Re can now be followed. (They are provided in the
1.82 -L4Re-Fiasco.OC-patches distribution.) This process should proceed without
1.83 -error.
1.84 +More information can be found in the docs directory in this distribution.
1.85
1.86 -As a consequence of building Fiasco.OC and L4Re, a payload can be generated
1.87 -and deployed for one of the examples provided by this software distribution.
1.88 -For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
1.89 -distribution, the following commands might be run:
1.90 -
1.91 -mkdir mybuild/images
1.92 -cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
1.93 -make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
1.94 -
1.95 -First, a directory for images or payloads is created. Here, it is assumed that
1.96 -the mybuild directory has been named for building L4Re.
1.97 -
1.98 -Then, a module list is copied from the conf/landfall-examples directory to
1.99 -conf/modules.list, this being the place where the build system obtains the
1.100 -details of the software to include in the payload.
1.101 -
1.102 -Finally, the make invocation combines programs and libraries found in the
1.103 -mybuild directory and uses the indicated payload to construct, in this case,
1.104 -an example demonstrating use of the Ben NanoNote's keypad.
1.105 -
1.106 -Deploying the Software
1.107 -----------------------
1.108 -
1.109 -The resulting payload should reside in the created images directory and be
1.110 -deployed to the appropriate location on storage media used to boot the target
1.111 -device. For the above example, the following payload would be created:
1.112 -
1.113 -mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage
1.114 -
1.115 -More information about deploying payloads and booting devices is provided in
1.116 -the L4Re-Fiasco.OC-patches distribution's documentation.
1.117 -
1.118 -Source Code Overview
1.119 -====================
1.120 -
1.121 -This distribution provides packages for use within L4Re, located in the pkg
1.122 -directory in this distribution and in the src/l4/pkg directory within the L4Re
1.123 -repository structure. They are currently as follows:
1.124 + * For reading in a text editor, see docs/wiki/Introduction
1.125 + * For reading in a Web browser, see docs/html/index.html
1.126
1.127 - devices - a collection of device drivers and libraries
1.128 - landfall-examples - a collection of examples demonstrating the devices
1.129 -
1.130 -In addition to the above, configuration files are provided for the example
1.131 -programs in the conf/landfall-examples directory.
1.132 -
1.133 -Device Support
1.134 -==============
1.135 -
1.136 -A selection of devices are supported by this software. They are found within
1.137 -the pkg/devices directory and are currently the following:
1.138 -
1.139 - backlight - display backlight control
1.140 - cpm - clock and power management
1.141 - display - device-specific display control
1.142 - fb - framebuffer access
1.143 - input - input event delivery
1.144 - keypad - keypad/keyboard scanning
1.145 - lcd - LCD and other display peripheral support
1.146 - pwm - pulse width modulation support
1.147 - spi - serial peripheral interface support
1.148 -
1.149 -Many device types provide the following kinds of support:
1.150 -
1.151 - * Server programs that regulate access to devices
1.152 - * Client libraries that provide access to the server programs
1.153 - * General library support for server programs to use
1.154 -
1.155 -In addition to the above, more general libraries found in the lib subdirectory
1.156 -provide abstractions for working with peripherals defined at the hardware
1.157 -level. It is envisaged that each peripheral-specific library will eventually
1.158 -have corresponding server support, at least where this would offer a
1.159 -reasonable kind of abstraction.
1.160 -
1.161 -(Some kinds of peripherals may, in fact, only be accessed when providing a
1.162 -device with different outward characteristics to those exposed at the hardware
1.163 -level. Other aspects of the hardware are also best maintained as libraries or
1.164 -data for use by other components, such as information about display panels.
1.165 -Such things do not need their own server whose only purpose would be to
1.166 -provide static data to other programs, and even then only very occasionally.)
1.167 -
1.168 -System Architecture
1.169 --------------------
1.170 +A Note about the Documentation
1.171 +------------------------------
1.172
1.173 -A significant motivation for providing server programs is to isolate
1.174 -device-specific operations within separate components, thus preventing each
1.175 -component from having too broad access to low-level system functionality. The
1.176 -combination of components is then encouraged to achieve configuration
1.177 -objectives.
1.178 -
1.179 -For example, two computing systems that employ the same LCD controller might
1.180 -each employ different screen types and have different ways of controlling
1.181 -display behaviour. By defining explicit mechanisms for combining access to
1.182 -these different aspects of the hardware, common elements (such as the LCD
1.183 -controller) may be encapsulated by a device server that can be reused, with
1.184 -differing elements (such as the screen type) being described by separate
1.185 -resources or components that can be introduced as required.
1.186 -
1.187 -Here is how the Ben NanoNote's framebuffer is supported by components:
1.188 -
1.189 - fb-drv (*) -> dev_cpm_jz4740 Clock configuration
1.190 - \-> dev_display_qi_lb60 Display control
1.191 - \-> dev_backlight_spi_ili8960 Backlight control
1.192 - \-> dev_spi_jz4740 Backlight communication
1.193 -
1.194 -And here is how the Letux 400's framebuffer is supported:
1.195 -
1.196 - fb-drv (*) -> dev_cpm_jz4730 Clock configuration
1.197 - \-> dev_display_letux400 Display control
1.198 - \-> dev_backlight_pwm Backlight control
1.199 - \-> dev_pwm_jz4730 Backlight communication
1.200 -
1.201 -(*) fb-drv links to the same generic JZ4740 LCD controller library in both
1.202 - cases
1.203 -
1.204 -Here, the CPM device provides access to the clock and power management
1.205 -functionality, the display device provides access to the backlight and is
1.206 -responsible for configuring pins for the display. Device servers are connected
1.207 -using capabilities (object references).
1.208 -
1.209 -Meanwhile, panel information is provided via a dynamically-loaded library:
1.210 -
1.211 - fb-drv <- mips-jz4740-panel.txt Library details
1.212 - \-> ... Library with panel data
1.213 +The original content in docs/wiki aims to be readable as plain text under most
1.214 +circumstances, but the intention is that this content be translated to HTML
1.215 +since it employs a formatting language based on the MoinMoin wiki format
1.216 +syntax.
1.217
1.218 -This method of obtaining a configured library name in order to load it
1.219 -dynamically is effectively equivalent to having a symbolic link identifying
1.220 -the library referencing the desired, specific library to be used. Since the
1.221 -"rom" virtual filesystem does not appear to support symbolic links, this
1.222 -method is used instead.
1.223 -
1.224 -By providing well-defined interfacing mechanisms, the behaviour of driver code
1.225 -can be parameterised using external components, and a proliferation of
1.226 -specially-constructed device drivers is hopefully avoided.
1.227 -
1.228 -Potential Improvements
1.229 -----------------------
1.230 -
1.231 -Some device servers could offer a broader range of operations and there could
1.232 -be increased consistency between implementations for different computing
1.233 -devices. For example, CPM servers only support operations necessary for LCD
1.234 -peripheral configuration.
1.235 -
1.236 -Additional device servers could be provided for peripherals already supported
1.237 -by libraries. For example, GPIO functionality is currently not exposed via a
1.238 -server. (L4Re's Io server seeks to support GPIO functionality in such a
1.239 -fashion.)
1.240 -
1.241 -Panel details are provided by libraries containing the structure definitions
1.242 -required by the LCD device code. These libraries may eventually be replaced by
1.243 -simple resource data files, but it is convenient to be able to use definitions
1.244 -found in header files and to take advantage of structure definitions by just
1.245 -encoding such details in source code and then turning such code into a
1.246 -library.
1.247 -
1.248 -Framebuffer device servers are not currently used, since fb-drv effectively
1.249 -offers the desired functionality together with other things.
1.250 -
1.251 -The input event device support needs to be made properly interoperable with
1.252 -the L4Re event framework so that existing software can be supplied with keypad
1.253 -events.
1.254 -
1.255 -Keypad device support should support interrupt handling to allow the scanning
1.256 -activity to sleep when no activity is taking place.
1.257 -
1.258 -Plenty of other hardware support should be introduced.
1.259 -
1.260 -Tools and Utilities
1.261 -===================
1.262 +The following command can be used to generate the HTML form of the
1.263 +documentation from the main directory of this distribution:
1.264
1.265 -The tools directory contains a number of programs useful when developing this
1.266 -software:
1.267 -
1.268 -checkconfig.sh - initialises files used to control run-time linking for the
1.269 - configured device
1.270 -
1.271 -install.sh - installs the software in a L4Re source distribution
1.272 -
1.273 -listlibs.sh - lists library modules for inclusion in .list files
1.274 -
1.275 -makecontrol.sh - updates the Control file for a package directory with
1.276 - details of the provided "virtual" packages employed by the
1.277 - build system for dependency resolution
1.278 -
1.279 -makefonts.sh - generate binary font files from source data
1.280 -
1.281 -readfont.py - convert GNU Unifont source files to binary form
1.282 +./docs/tools/make_docs.sh
1.283
1.284 -Identifying Library Modules
1.285 ----------------------------
1.286 -
1.287 -The listlibs.sh tool is intended to inspect an existing .list file, analyse
1.288 -executable programs mentioned in that file that have already been built, and
1.289 -to generate a list of shared libraries needed by those executables such that
1.290 -the .list file describes all required modules for deployment.
1.291 -
1.292 -In the l4 subdirectory of the L4Re source distribution, the tool is run as
1.293 -follows:
1.294 -
1.295 -$LANDFALL/tools/listlibs.sh conf/landfall-examples/$EXAMPLE.list mybuild
1.296 -
1.297 -(Here, $LANDFALL needs to expand to the location of this distribution whereas
1.298 -$EXAMPLE indicates an example name.)
1.299 -
1.300 -For example:
1.301 -
1.302 -~/L4/Landfall/tools/listlibs.sh \
1.303 - conf/landfall-examples/mips-qi_lb60-keypad.list mybuild
1.304 +Specify the --web option for Web server deployment:
1.305
1.306 -This will output a list of modules for inclusion in the .list file. It can be
1.307 -advisable to make this change to the .list file in the Landfall distribution
1.308 -and to then install the file into the L4Re source distribution, potentially
1.309 -using the install.sh script.
1.310 -
1.311 -At this point, it is important to remember that the conf/modules.list file
1.312 -will need updating to include these new details. For example:
1.313 -
1.314 -cp conf/landfall-examples/mips-qi_lb60-keypad.list conf/modules.list
1.315 -
1.316 -Finally, the command to build a payload can be run:
1.317 -
1.318 -make O=mybuild uimage E=mips-qi_lb60-keypad-example
1.319 -
1.320 -This should consult conf/modules.list and update the contents of the generated
1.321 -image to include any newly-added shared libraries.
1.322 -
1.323 -Dependencies/Prerequisites
1.324 -==========================
1.325 -
1.326 -Landfall has the following general dependencies or prerequisites:
1.327 +./docs/tools/make_docs.sh --web
1.328
1.329 -Prerequisite Suggestions
1.330 ------------- -----------
1.331 -
1.332 -Basic development tools Debian package: build-essential
1.333 -(for building the software)
1.334 -
1.335 -Cross-toolchains Buildroot C/C++ toolchains
1.336 -(for building the software) https://buildroot.org/
1.337 - or Debian toolchains (for the CI20)
1.338 -
1.339 -GNU Unifont Tested with Debian version 1:5.1.20080914-1.3
1.340 -(needed to display text) http://unifoundry.com/unifont.html
1.341 -
1.342 -L4Re Tested with repository version r78
1.343 -(this work's foundation) http://l4re.org/
1.344 -
1.345 -L4Re-Fiasco.OC-patches Tested with snapshot-20180530
1.346 -(needed for device support) http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html
1.347 -
1.348 -Python Tested with Debian version 2.7.3-4+deb7u1
1.349 -(needed to run tools) https://www.python.org/
1.350 -
1.351 -See also the prerequisites for the L4Re-Fiasco.OC-patches distribution,
1.352 -described in that distribution's documentation.
1.353 +To generate individual documents, specify their names after any options.
1.354
1.355 Copyright and Licence Information
1.356 =================================
2.1 --- a/docs/COPYING.txt Wed Feb 20 15:31:14 2019 +0100
2.2 +++ b/docs/COPYING.txt Sat Apr 13 19:28:39 2019 +0200
2.3 @@ -21,7 +21,7 @@
2.4 If not, write to the Free Software Foundation, Inc.,
2.5 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
2.6
2.7 -
2.8 +----
2.9
2.10 Other code has been incorporated into this distribution and is covered by the
2.11 following copyrights:
2.12 @@ -56,7 +56,7 @@
2.13
2.14 (c) 2008-2009 Adam Lackorzynski <adam@os.inf.tu-dresden.de>
2.15
2.16 -
2.17 +----
2.18
2.19 Font definitions and licence when bitmap data has been generated by the
2.20 appropriate tool (see unifont.tff for bitmap data derived from GNU Unifont's
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/tools/make_docs.sh Sat Apr 13 19:28:39 2019 +0200
3.3 @@ -0,0 +1,19 @@
3.4 +#!/bin/sh
3.5 +
3.6 +if [ "$1" = '--web' ] ; then
3.7 + DOCINDEX=
3.8 + shift 1
3.9 +else
3.10 + DOCINDEX='--document-index index.html'
3.11 +fi
3.12 +
3.13 +FILENAMES=${*:-'--all'}
3.14 +
3.15 +moinconvert --input-dir docs/wiki \
3.16 + --output-dir docs/html \
3.17 + --input-page-sep '--' \
3.18 + --root Introduction \
3.19 + --theme mercurial --format html \
3.20 + --macros \
3.21 + $DOCINDEX \
3.22 + $FILENAMES
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/wiki/Downloads Sat Apr 13 19:28:39 2019 +0200
4.3 @@ -0,0 +1,33 @@
4.4 += Downloads =
4.5 +
4.6 +Remember that certain [[../Prerequisites|prerequisites]] are needed for the
4.7 +software to work.
4.8 +
4.9 +== Copyright and Licence ==
4.10 +
4.11 +The Landfall distribution is licensed under the
4.12 +[[http://www.gnu.org/copyleft/gpl.html|GPL]] version 2 or later. However, a
4.13 +small amount of incorporated code with origins in L4Re has a "version 2 only"
4.14 +licence which may affect redistributions of systems based on this work,
4.15 +preventing recipients from applying the provisions of later GPL versions.
4.16 +
4.17 +== Repository ==
4.18 +
4.19 +The source code repository is located at the following location:
4.20 +
4.21 +[[http://hgweb.boddie.org.uk/Landfall]]
4.22 +
4.23 +The repository can be cloned using [[https://www.mercurial-scm.org/|Mercurial]]
4.24 +as follows:
4.25 +
4.26 +{{{
4.27 +hg clone http://hgweb.boddie.org.uk/Lichen
4.28 +}}}
4.29 +
4.30 +If you are familiar with version control systems and Mercurial in particular,
4.31 +it can be convenient to use this approach to obtain and update the software,
4.32 +although you should be aware that updates made available in the repository
4.33 +may, if deployed, cause the software to not function correctly on occasion,
4.34 +even if attempts are made to avoid such situations. Therefore, you should
4.35 +choose to update with care and be prepared to switch to a "known working"
4.36 +revision if necessary.
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/wiki/Future_Work Sat Apr 13 19:28:39 2019 +0200
5.3 @@ -0,0 +1,30 @@
5.4 += Future Work =
5.5 +
5.6 +Some device servers could offer a broader range of operations and there could
5.7 +be increased consistency between implementations for different computing
5.8 +devices. For example, CPM servers only support operations necessary for LCD
5.9 +peripheral configuration.
5.10 +
5.11 +Additional device servers could be provided for peripherals already supported
5.12 +by libraries. For example, GPIO functionality is currently not exposed via a
5.13 +server. (L4Re's Io server seeks to support GPIO functionality in such a
5.14 +fashion.)
5.15 +
5.16 +Panel details are provided by libraries containing the structure definitions
5.17 +required by the LCD device code. These libraries may eventually be replaced by
5.18 +simple resource data files, but it is convenient to be able to use definitions
5.19 +found in header files and to take advantage of structure definitions by just
5.20 +encoding such details in source code and then turning such code into a
5.21 +library.
5.22 +
5.23 +Framebuffer device servers are not currently used, since fb-drv effectively
5.24 +offers the desired functionality together with other things.
5.25 +
5.26 +The input event device support needs to be made properly interoperable with
5.27 +the L4Re event framework so that existing software can be supplied with keypad
5.28 +events.
5.29 +
5.30 +Keypad device support should support interrupt handling to allow the scanning
5.31 +activity to sleep when no activity is taking place.
5.32 +
5.33 +Plenty of other hardware support should be introduced.
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/wiki/Getting_Started Sat Apr 13 19:28:39 2019 +0200
6.3 @@ -0,0 +1,111 @@
6.4 += Getting Started =
6.5 +
6.6 +To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
6.7 +source distribution:
6.8 +
6.9 +[[http://l4re.org/download.html]]
6.10 +
6.11 +With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
6.12 +need to be applied. This patch distribution can be obtained from the following
6.13 +location:
6.14 +
6.15 +[[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html]]
6.16 +
6.17 +The "current archive" should be obtained since the "initial archive" is merely
6.18 +provided for historical purposes. Instructions about applying the patches are
6.19 +provided in the distributed archive, as is a summary of the issues related to
6.20 +configuring and building the software. Building can be done after the steps
6.21 +described below.
6.22 +
6.23 +Some dependencies are also needed and these are documented in a section below.
6.24 +To actually build the software, various development tools are required, and
6.25 +suggestions are also provided in the dependencies section.
6.26 +
6.27 +== Configuring this Software ==
6.28 +
6.29 +Some files may need to be adjusted for the device on which the software is to
6.30 +be deployed. A script is provided to check and update them:
6.31 +
6.32 +{{{
6.33 +$LANDFALL/tools/checkconfig.sh $PLATFORM
6.34 +}}}
6.35 +
6.36 +(Here, `$LANDFALL` needs to expand to the location of this distribution
6.37 +whereas `$PLATFORM` indicates a platform type.)
6.38 +
6.39 +For example:
6.40 +
6.41 +{{{
6.42 +~/L4/Landfall/tools/checkconfig.sh qi_lb60
6.43 +}}}
6.44 +
6.45 +This configures the files for the Ben NanoNote. See the following file for a
6.46 +list of supported platforms:
6.47 +
6.48 +{{{
6.49 +conf/landfall-examples/platforms.txt
6.50 +}}}
6.51 +
6.52 +== Installing this Software ==
6.53 +
6.54 +With the above patches applied, this software can be installed within the
6.55 +unpacked L4Re/Fiasco.OC distribution using a command of the following form:
6.56 +
6.57 +{{{
6.58 +$LANDFALL/tools/install.sh $L4DIR
6.59 +}}}
6.60 +
6.61 +(Here, `$LANDFALL` needs to expand to the location of this distribution
6.62 +whereas `$L4DIR` needs to expand to the location of the L4Re/Fiasco.OC
6.63 +software.)
6.64 +
6.65 +For example:
6.66 +
6.67 +{{{
6.68 +~/L4/Landfall/tools/install.sh ~/L4/src
6.69 +}}}
6.70 +
6.71 +(The repository root of the L4Re/Fiasco.OC distribution typically has a
6.72 +directory name of `src`.)
6.73 +
6.74 +== Building the Software ==
6.75 +
6.76 +With this software installed into the appropriate location, the instructions
6.77 +for building Fiasco.OC and L4Re can now be followed. (They are provided in the
6.78 +L4Re-Fiasco.OC-patches distribution.) This process should proceed without
6.79 +error.
6.80 +
6.81 +As a consequence of building Fiasco.OC and L4Re, a payload can be generated
6.82 +and deployed for one of the examples provided by this software distribution.
6.83 +For example, in the l4 subdirectory of the unpacked L4Re/Fiasco.OC
6.84 +distribution, the following commands might be run:
6.85 +
6.86 +{{{
6.87 +mkdir mybuild/images
6.88 +cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
6.89 +make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
6.90 +}}}
6.91 +
6.92 +First, a directory for images or payloads is created. Here, it is assumed that
6.93 +the `mybuild` directory has been named for building L4Re.
6.94 +
6.95 +Then, a module list is copied from the conf/landfall-examples directory to
6.96 +`conf/modules.list`, this being the place where the build system obtains the
6.97 +details of the software to include in the payload.
6.98 +
6.99 +Finally, the make invocation combines programs and libraries found in the
6.100 +`mybuild` directory and uses the indicated payload to construct, in this case,
6.101 +an example demonstrating use of the Ben NanoNote's keypad.
6.102 +
6.103 +== Deploying the Software ==
6.104 +
6.105 +The resulting payload should reside in the created images directory and be
6.106 +deployed to the appropriate location on storage media used to boot the target
6.107 +device. For the above example, the following payload would be created:
6.108 +
6.109 +{{{
6.110 +mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage
6.111 +}}}
6.112 +
6.113 +More information about deploying payloads and booting devices is provided in
6.114 +the L4Re-Fiasco.OC-patches distribution's documentation.
7.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
7.2 +++ b/docs/wiki/Introduction Sat Apr 13 19:28:39 2019 +0200
7.3 @@ -0,0 +1,27 @@
7.4 += Landfall =
7.5 +
7.6 +Landfall is a distribution of components for the [[http://www.l4re.org/|L4
7.7 +Runtime Environment]] (L4Re) providing device support and examples for
7.8 +peripherals and hardware features of various computing devices, initially
7.9 +supporting the following devices:
7.10 +
7.11 + * [[http://en.qi-hardware.com/wiki/Ben_NanoNote|Ben NanoNote]]
7.12 + * [[http://projects.goldelico.com/p/letux400/|Letux 400]]
7.13 + * [[https://www.elinux.org/MIPS_Creator_CI20|MIPS Creator CI20]]
7.14 +
7.15 +It builds on [[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html|work]] done
7.16 +to make L4Re available on these platforms, itself building on work by others
7.17 +to port L4Re and Fiasco.OC to the MIPS architecture.
7.18 +
7.19 +{{attachment:P5300454-800x600.JPG||alt=The Spectrum example on the Ben
7.20 +NanoNote and Letux 400}}
7.21 +
7.22 +== Documentation ==
7.23 +
7.24 + * [[Downloads]]
7.25 + * [[Getting Started]]
7.26 + * [[Future Work]]
7.27 + * [[Prerequisites]]
7.28 + * [[Source Code]]
7.29 + * [[System Architecture]]
7.30 + * [[Tools]]
8.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
8.2 +++ b/docs/wiki/Prerequisites Sat Apr 13 19:28:39 2019 +0200
8.3 @@ -0,0 +1,37 @@
8.4 += Prerequisites =
8.5 +
8.6 +Landfall has the following general dependencies or prerequisites:
8.7 +
8.8 +{{{#!table
8.9 +'''Prerequisite''' || '''Suggestions'''
8.10 +==
8.11 +Basic development tools
8.12 +(for building the software) || Debian package: build-essential
8.13 +==
8.14 +Cross-toolchains
8.15 +(for building the software) || Buildroot C/C++ toolchains \\
8.16 + .. [[https://buildroot.org/]] \\
8.17 + .. or Debian toolchains (for the CI20)
8.18 +==
8.19 +GNU Unifont
8.20 +(needed to display text) || Tested with Debian version 1:5.1.20080914-1.3 \\
8.21 + .. [[http://unifoundry.com/unifont.html]]
8.22 +==
8.23 +L4Re
8.24 +(this work's foundation) || Tested with repository version r78 \\
8.25 + .. [[http://l4re.org/]]
8.26 +==
8.27 +L4Re-Fiasco.OC-patches
8.28 +(needed for device support) || Tested with snapshot-20180530 \\
8.29 + .. [[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html]]
8.30 +==
8.31 +MoinLight
8.32 +(needed for documentation) || [[http://projects.boddie.org.uk/MoinLight]]
8.33 +==
8.34 +Python
8.35 +(needed to run tools) || Tested with Debian version 2.7.3-4+deb7u1 \\
8.36 + .. [[https://www.python.org/]]
8.37 +}}}
8.38 +
8.39 +See also the prerequisites for the L4Re-Fiasco.OC-patches distribution,
8.40 +described in that distribution's documentation.
9.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
9.2 +++ b/docs/wiki/Source_Code Sat Apr 13 19:28:39 2019 +0200
9.3 @@ -0,0 +1,47 @@
9.4 += Source Code Overview =
9.5 +
9.6 +This distribution provides packages for use within L4Re, located in the `pkg`
9.7 +directory in this distribution and in the `src/l4/pkg` directory within the
9.8 +L4Re repository structure. They are currently as follows:
9.9 +
9.10 +|| '''Package''' || '''Description''' ||
9.11 +|| devices || a collection of device drivers and libraries ||
9.12 +|| landfall-examples || a collection of examples demonstrating the devices ||
9.13 +
9.14 +In addition to the above, configuration files are provided for the example
9.15 +programs in the `conf/landfall-examples` directory.
9.16 +
9.17 +== Device Support ==
9.18 +
9.19 +A selection of devices are supported by this software. They are found within
9.20 +the `pkg/devices` directory and are currently the following:
9.21 +
9.22 +|| '''Device''' || '''Description''' ||
9.23 +|| backlight || display backlight control ||
9.24 +|| cpm || clock and power management ||
9.25 +|| display || device-specific display control ||
9.26 +|| fb || framebuffer access ||
9.27 +|| input || input event delivery ||
9.28 +|| keypad || keypad/keyboard scanning ||
9.29 +|| lcd || LCD and other display peripheral support ||
9.30 +|| pwm || pulse width modulation support ||
9.31 +|| spi || serial peripheral interface support ||
9.32 +
9.33 +Many device types provide the following kinds of support:
9.34 +
9.35 + * Server programs that regulate access to devices
9.36 + * Client libraries that provide access to the server programs
9.37 + * General library support for server programs to use
9.38 +
9.39 +In addition to the above, more general libraries found in the lib subdirectory
9.40 +provide abstractions for working with peripherals defined at the hardware
9.41 +level. It is envisaged that each peripheral-specific library will eventually
9.42 +have corresponding server support, at least where this would offer a
9.43 +reasonable kind of abstraction.
9.44 +
9.45 +(Some kinds of peripherals may, in fact, only be accessed when providing a
9.46 +device with different outward characteristics to those exposed at the hardware
9.47 +level. Other aspects of the hardware are also best maintained as libraries or
9.48 +data for use by other components, such as information about display panels.
9.49 +Such things do not need their own server whose only purpose would be to
9.50 +provide static data to other programs, and even then only very occasionally.)
10.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
10.2 +++ b/docs/wiki/System_Architecture Sat Apr 13 19:28:39 2019 +0200
10.3 @@ -0,0 +1,103 @@
10.4 += System Architecture =
10.5 +
10.6 +A significant motivation for providing server programs is to isolate
10.7 +device-specific operations within separate components, thus preventing each
10.8 +component from having too broad access to low-level system functionality. The
10.9 +combination of components is then encouraged to achieve configuration
10.10 +objectives.
10.11 +
10.12 +For example, two computing systems that employ the same LCD controller might
10.13 +each employ different screen types and have different ways of controlling
10.14 +display behaviour. By defining explicit mechanisms for combining access to
10.15 +these different aspects of the hardware, common elements (such as the LCD
10.16 +controller) may be encapsulated by a device server that can be reused, with
10.17 +differing elements (such as the screen type) being described by separate
10.18 +resources or components that can be introduced as required.
10.19 +
10.20 +Here is how the Ben NanoNote's framebuffer is supported by components:
10.21 +
10.22 +######## A graph showing the relationship between components.
10.23 +
10.24 +{{{#!graphviz
10.25 +#format svg
10.26 +#transform notugly
10.27 +digraph nanonote_framebuffer {
10.28 + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"];
10.29 +
10.30 + fb_drv [label="fb-drv"];
10.31 + dev_cpm_jz4740 [label="dev_cpm_jz4740\nClock configuration"];
10.32 + dev_display_qi_lb60 [label="dev_display_qi_lb60\nDisplay control"];
10.33 + dev_backlight_spi_ili8960 [label="dev_backlight_spi_ili8960\nBacklight control"];
10.34 + dev_spi_jz4740 [label="dev_spi_jz4740\nBacklight communication"];
10.35 +
10.36 + fb_drv -> dev_cpm_jz4740;
10.37 + fb_drv -> dev_display_qi_lb60 -> dev_backlight_spi_ili8960 -> dev_spi_jz4740;
10.38 +}
10.39 +}}}
10.40 +
10.41 +########
10.42 +
10.43 +And here is how the Letux 400's framebuffer is supported:
10.44 +
10.45 +######## A graph showing the relationship between components.
10.46 +
10.47 +{{{#!graphviz
10.48 +#format svg
10.49 +#transform notugly
10.50 +digraph letux400_framebuffer {
10.51 + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"];
10.52 +
10.53 + fb_drv [label="fb-drv"];
10.54 + dev_cpm_jz4730 [label="dev_cpm_jz4730\nClock configuration"];
10.55 + dev_display_letux400 [label="dev_display_letux400\nDisplay control"];
10.56 + dev_backlight_pwm [label="dev_backlight_pwm\nBacklight control"];
10.57 + dev_pwm_jz4730 [label="dev_pwm_jz4730\nBacklight communication"];
10.58 +
10.59 + fb_drv -> dev_cpm_jz4730;
10.60 + fb_drv -> dev_display_letux400 -> dev_backlight_pwm -> dev_pwm_jz4730;
10.61 +}
10.62 +}}}
10.63 +
10.64 +########
10.65 +
10.66 +Note that fb-drv links to the same generic JZ4740 LCD controller library in
10.67 +both cases
10.68 +
10.69 +Here, the CPM device provides access to the clock and power management
10.70 +functionality, the display device provides access to the backlight and is
10.71 +responsible for configuring pins for the display. Device servers are connected
10.72 +using capabilities (object references).
10.73 +
10.74 +Meanwhile, panel information is provided via a dynamically-loaded library:
10.75 +
10.76 +######## A graph showing the acquisition of panel information.
10.77 +
10.78 +{{{#!graphviz
10.79 +#format svg
10.80 +#transform notugly
10.81 +digraph panel_information {
10.82 + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"];
10.83 +
10.84 + subgraph {
10.85 + rank=min;
10.86 + fb_drv [label="fb-drv"];
10.87 + }
10.88 +
10.89 + paneldata [label="mips-jz4740-panel.txt\nLibrary details"];
10.90 + library [label="...\nLibrary with panel data"];
10.91 +
10.92 + paneldata -> fb_drv -> library;
10.93 +}
10.94 +}}}
10.95 +
10.96 +########
10.97 +
10.98 +This method of obtaining a configured library name in order to load it
10.99 +dynamically is effectively equivalent to having a symbolic link identifying
10.100 +the library referencing the desired, specific library to be used. Since the
10.101 +"rom" virtual filesystem does not appear to support symbolic links, this
10.102 +method is used instead.
10.103 +
10.104 +By providing well-defined interfacing mechanisms, the behaviour of driver code
10.105 +can be parameterised using external components, and a proliferation of
10.106 +specially-constructed device drivers is hopefully avoided.
11.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
11.2 +++ b/docs/wiki/Tools Sat Apr 13 19:28:39 2019 +0200
11.3 @@ -0,0 +1,66 @@
11.4 += Tools and Utilities =
11.5 +
11.6 +The `tools` directory contains a number of programs useful when developing
11.7 +this software:
11.8 +
11.9 +{{{#!table
11.10 +checkconfig.sh || initialises files used to control run-time linking for the
11.11 + .. configured device
11.12 +==
11.13 +install.sh || installs the software in a L4Re source distribution
11.14 +==
11.15 +listlibs.sh || lists library modules for inclusion in .list files
11.16 +==
11.17 +makecontrol.sh || updates the Control file for a package directory with
11.18 + .. details of the provided "virtual" packages employed by the
11.19 + .. build system for dependency resolution
11.20 +==
11.21 +makefonts.sh || generate binary font files from source data
11.22 +==
11.23 +readfont.py || convert GNU Unifont source files to binary form
11.24 +}}}
11.25 +
11.26 +== Identifying Library Modules ==
11.27 +
11.28 +The `listlibs.sh` tool is intended to inspect an existing .list file, analyse
11.29 +executable programs mentioned in that file that have already been built, and
11.30 +to generate a list of shared libraries needed by those executables such that
11.31 +the .list file describes all required modules for deployment.
11.32 +
11.33 +In the `l4` subdirectory of the L4Re source distribution, the tool is run as
11.34 +follows:
11.35 +
11.36 +{{{
11.37 +$LANDFALL/tools/listlibs.sh conf/landfall-examples/$EXAMPLE.list mybuild
11.38 +}}}
11.39 +
11.40 +(Here, `$LANDFALL` needs to expand to the location of this distribution
11.41 +whereas `$EXAMPLE` indicates an example name.)
11.42 +
11.43 +For example:
11.44 +
11.45 +{{{
11.46 +~/L4/Landfall/tools/listlibs.sh \
11.47 + conf/landfall-examples/mips-qi_lb60-keypad.list mybuild
11.48 +}}}
11.49 +
11.50 +This will output a list of modules for inclusion in the .list file. It can be
11.51 +advisable to make this change to the .list file in the Landfall distribution
11.52 +and to then install the file into the L4Re source distribution, potentially
11.53 +using the install.sh script.
11.54 +
11.55 +At this point, it is important to remember that the `conf/modules.list` file
11.56 +will need updating to include these new details. For example:
11.57 +
11.58 +{{{
11.59 +cp conf/landfall-examples/mips-qi_lb60-keypad.list conf/modules.list
11.60 +}}}
11.61 +
11.62 +Finally, the command to build a payload can be run:
11.63 +
11.64 +{{{
11.65 +make O=mybuild uimage E=mips-qi_lb60-keypad-example
11.66 +}}}
11.67 +
11.68 +This should consult `conf/modules.list` and update the contents of the
11.69 +generated image to include any newly-added shared libraries.
12.1 Binary file docs/wiki/attachments/P5300454-800x600.JPG has changed