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 =================================