# HG changeset patch # User Paul Boddie # Date 1555176519 -7200 # Node ID 1e9751847d3323e849c71fcbed0458b471a59666 # Parent 3cf80b18e7194567f430289e8eec4921897eeb15 Introduced wiki-format documents as the principal documentation. diff -r 3cf80b18e719 -r 1e9751847d33 README.txt --- a/README.txt Wed Feb 20 15:31:14 2019 +0100 +++ b/README.txt Sat Apr 13 19:28:39 2019 +0200 @@ -6,338 +6,29 @@ various computing devices, initially supporting the Ben NanoNote and Letux 400 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 -=============== - -To use this software, it is necessary to first obtain the L4Re and Fiasco.OC -source distribution: - -http://l4re.org/download.html - -With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution -need to be applied. This patch distribution can be obtained from the following -location: - -http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html - -The "current archive" should be obtained since the "initial archive" is merely -provided for historical purposes. Instructions about applying the patches are -provided in the distributed archive, as is a summary of the issues related to -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 $PLATFORM - -(Here, $LANDFALL needs to expand to the location of this distribution whereas -$PLATFORM indicates a platform type.) - -For example: - -~/L4/Landfall/tools/checkconfig.sh qi_lb60 - -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 ------------------------- - -With the above patches applied, this software can be installed within the -unpacked L4Re/Fiasco.OC distribution using a command of the following form: - -$LANDFALL/tools/install.sh $L4DIR - -(Here, $LANDFALL needs to expand to the location of this distribution whereas -$L4DIR needs to expand to the location of the L4Re/Fiasco.OC software.) - -For example: - -~/L4/Landfall/tools/install.sh ~/L4/src - -(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. (They are provided in the -L4Re-Fiasco.OC-patches distribution.) This process should proceed without -error. +More information can be found in the docs directory in this distribution. -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 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. - -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 pkg -directory in this distribution and in the src/l4/pkg directory within the L4Re -repository structure. They are currently as follows: + * For reading in a text editor, see docs/wiki/Introduction + * For reading in a Web browser, see docs/html/index.html - devices - a collection of device drivers and libraries - landfall-examples - a collection of examples demonstrating the devices - -In addition to the above, configuration files are provided for the example -programs in the conf/landfall-examples directory. - -Device Support -============== - -A selection of devices are supported by this software. They are found within -the pkg/devices directory and are currently the following: - - backlight - display backlight control - cpm - clock and power management - display - device-specific display control - fb - framebuffer access - input - input event delivery - keypad - keypad/keyboard scanning - lcd - LCD and other display peripheral support - pwm - pulse width modulation support - spi - serial peripheral interface support - -Many device types provide the following kinds of support: - - * Server programs that regulate access to devices - * Client libraries that provide access to the server programs - * General library support for server programs to use - -In addition to the above, more general libraries found in the lib subdirectory -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, 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 Note about the Documentation +------------------------------ -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. 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 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. - -Here is how the Ben NanoNote's framebuffer is supported by components: - - fb-drv (*) -> dev_cpm_jz4740 Clock configuration - \-> dev_display_qi_lb60 Display control - \-> dev_backlight_spi_ili8960 Backlight control - \-> dev_spi_jz4740 Backlight communication - -And here is how the Letux 400's framebuffer is supported: - - fb-drv (*) -> dev_cpm_jz4730 Clock configuration - \-> dev_display_letux400 Display control - \-> dev_backlight_pwm Backlight control - \-> dev_pwm_jz4730 Backlight communication - -(*) fb-drv links to the same generic JZ4740 LCD controller library in both - cases - -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. 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 +The original content in docs/wiki aims to be readable as plain text under most +circumstances, but the intention is that this content be translated to HTML +since it employs a formatting language based on the MoinMoin wiki format +syntax. -This method of obtaining a configured library name in order to load it -dynamically is effectively equivalent to having a symbolic link identifying -the library referencing the desired, specific library to be used. Since the -"rom" virtual filesystem does not appear to support symbolic links, this -method is used instead. - -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 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. (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, 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. - -The input event device support needs to be made properly interoperable with -the L4Re event framework so that existing software can be supplied with keypad -events. - -Keypad device support should support interrupt handling to allow the scanning -activity to sleep when no activity is taking place. - -Plenty of other hardware support should be introduced. - -Tools and Utilities -=================== +The following command can be used to generate the HTML form of the +documentation from the main directory of this distribution: -The tools directory contains a number of programs useful when developing this -software: - -checkconfig.sh - initialises files used to control run-time linking for the - configured device - -install.sh - installs the software in a L4Re source distribution - -listlibs.sh - lists library modules for inclusion in .list files - -makecontrol.sh - updates the Control file for a package directory with - details of the provided "virtual" packages employed by the - build system for dependency resolution - -makefonts.sh - generate binary font files from source data - -readfont.py - convert GNU Unifont source files to binary form +./docs/tools/make_docs.sh -Identifying Library Modules ---------------------------- - -The listlibs.sh tool is intended to inspect an existing .list file, analyse -executable programs mentioned in that file that have already been built, and -to generate a list of shared libraries needed by those executables such that -the .list file describes all required modules for deployment. - -In the l4 subdirectory of the L4Re source distribution, the tool is run as -follows: - -$LANDFALL/tools/listlibs.sh conf/landfall-examples/$EXAMPLE.list mybuild - -(Here, $LANDFALL needs to expand to the location of this distribution whereas -$EXAMPLE indicates an example name.) - -For example: - -~/L4/Landfall/tools/listlibs.sh \ - conf/landfall-examples/mips-qi_lb60-keypad.list mybuild +Specify the --web option for Web server deployment: -This will output a list of modules for inclusion in the .list file. It can be -advisable to make this change to the .list file in the Landfall distribution -and to then install the file into the L4Re source distribution, potentially -using the install.sh script. - -At this point, it is important to remember that the conf/modules.list file -will need updating to include these new details. For example: - -cp conf/landfall-examples/mips-qi_lb60-keypad.list conf/modules.list - -Finally, the command to build a payload can be run: - -make O=mybuild uimage E=mips-qi_lb60-keypad-example - -This should consult conf/modules.list and update the contents of the generated -image to include any newly-added shared libraries. - -Dependencies/Prerequisites -========================== - -Landfall has the following general dependencies or prerequisites: +./docs/tools/make_docs.sh --web -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 - -L4Re Tested with repository version r78 -(this work's foundation) http://l4re.org/ - -L4Re-Fiasco.OC-patches Tested with snapshot-20180530 -(needed for device support) http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.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. +To generate individual documents, specify their names after any options. Copyright and Licence Information ================================= diff -r 3cf80b18e719 -r 1e9751847d33 docs/COPYING.txt --- a/docs/COPYING.txt Wed Feb 20 15:31:14 2019 +0100 +++ b/docs/COPYING.txt Sat Apr 13 19:28:39 2019 +0200 @@ -21,7 +21,7 @@ If not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - +---- Other code has been incorporated into this distribution and is covered by the following copyrights: @@ -56,7 +56,7 @@ (c) 2008-2009 Adam Lackorzynski - +---- Font definitions and licence when bitmap data has been generated by the appropriate tool (see unifont.tff for bitmap data derived from GNU Unifont's diff -r 3cf80b18e719 -r 1e9751847d33 docs/tools/make_docs.sh --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/tools/make_docs.sh Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,19 @@ +#!/bin/sh + +if [ "$1" = '--web' ] ; then + DOCINDEX= + shift 1 +else + DOCINDEX='--document-index index.html' +fi + +FILENAMES=${*:-'--all'} + +moinconvert --input-dir docs/wiki \ + --output-dir docs/html \ + --input-page-sep '--' \ + --root Introduction \ + --theme mercurial --format html \ + --macros \ + $DOCINDEX \ + $FILENAMES diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Downloads --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Downloads Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,33 @@ += Downloads = + +Remember that certain [[../Prerequisites|prerequisites]] are needed for the +software to work. + +== Copyright and Licence == + +The Landfall distribution is licensed under the +[[http://www.gnu.org/copyleft/gpl.html|GPL]] version 2 or later. However, a +small amount of incorporated code with origins in L4Re has a "version 2 only" +licence which may affect redistributions of systems based on this work, +preventing recipients from applying the provisions of later GPL versions. + +== Repository == + +The source code repository is located at the following location: + +[[http://hgweb.boddie.org.uk/Landfall]] + +The repository can be cloned using [[https://www.mercurial-scm.org/|Mercurial]] +as follows: + +{{{ +hg clone http://hgweb.boddie.org.uk/Lichen +}}} + +If you are familiar with version control systems and Mercurial in particular, +it can be convenient to use this approach to obtain and update the software, +although you should be aware that updates made available in the repository +may, if deployed, cause the software to not function correctly on occasion, +even if attempts are made to avoid such situations. Therefore, you should +choose to update with care and be prepared to switch to a "known working" +revision if necessary. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Future_Work --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Future_Work Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,30 @@ += Future Work = + +Some device servers could offer a broader range of operations and there could +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. (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, 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. + +The input event device support needs to be made properly interoperable with +the L4Re event framework so that existing software can be supplied with keypad +events. + +Keypad device support should support interrupt handling to allow the scanning +activity to sleep when no activity is taking place. + +Plenty of other hardware support should be introduced. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Getting_Started --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Getting_Started Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,111 @@ += Getting Started = + +To use this software, it is necessary to first obtain the L4Re and Fiasco.OC +source distribution: + +[[http://l4re.org/download.html]] + +With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution +need to be applied. This patch distribution can be obtained from the following +location: + +[[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html]] + +The "current archive" should be obtained since the "initial archive" is merely +provided for historical purposes. Instructions about applying the patches are +provided in the distributed archive, as is a summary of the issues related to +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 $PLATFORM +}}} + +(Here, `$LANDFALL` needs to expand to the location of this distribution +whereas `$PLATFORM` indicates a platform type.) + +For example: + +{{{ +~/L4/Landfall/tools/checkconfig.sh qi_lb60 +}}} + +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 == + +With the above patches applied, this software can be installed within the +unpacked L4Re/Fiasco.OC distribution using a command of the following form: + +{{{ +$LANDFALL/tools/install.sh $L4DIR +}}} + +(Here, `$LANDFALL` needs to expand to the location of this distribution +whereas `$L4DIR` needs to expand to the location of the L4Re/Fiasco.OC +software.) + +For example: + +{{{ +~/L4/Landfall/tools/install.sh ~/L4/src +}}} + +(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. (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 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. + +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. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Introduction --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Introduction Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,27 @@ += Landfall = + +Landfall is a distribution of components for the [[http://www.l4re.org/|L4 +Runtime Environment]] (L4Re) providing device support and examples for +peripherals and hardware features of various computing devices, initially +supporting the following devices: + + * [[http://en.qi-hardware.com/wiki/Ben_NanoNote|Ben NanoNote]] + * [[http://projects.goldelico.com/p/letux400/|Letux 400]] + * [[https://www.elinux.org/MIPS_Creator_CI20|MIPS Creator CI20]] + +It builds on [[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html|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. + +{{attachment:P5300454-800x600.JPG||alt=The Spectrum example on the Ben +NanoNote and Letux 400}} + +== Documentation == + + * [[Downloads]] + * [[Getting Started]] + * [[Future Work]] + * [[Prerequisites]] + * [[Source Code]] + * [[System Architecture]] + * [[Tools]] diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Prerequisites --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Prerequisites Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,37 @@ += Prerequisites = + +Landfall has the following general dependencies or prerequisites: + +{{{#!table +'''Prerequisite''' || '''Suggestions''' +== +Basic development tools +(for building the software) || Debian package: build-essential +== +Cross-toolchains +(for building the software) || Buildroot C/C++ toolchains \\ + .. [[https://buildroot.org/]] \\ + .. or Debian toolchains (for the CI20) +== +GNU Unifont +(needed to display text) || Tested with Debian version 1:5.1.20080914-1.3 \\ + .. [[http://unifoundry.com/unifont.html]] +== +L4Re +(this work's foundation) || Tested with repository version r78 \\ + .. [[http://l4re.org/]] +== +L4Re-Fiasco.OC-patches +(needed for device support) || Tested with snapshot-20180530 \\ + .. [[http://www.boddie.org.uk/paul/L4Re-Fiasco.OC.html]] +== +MoinLight +(needed for documentation) || [[http://projects.boddie.org.uk/MoinLight]] +== +Python +(needed to run tools) || Tested with Debian version 2.7.3-4+deb7u1 \\ + .. [[https://www.python.org/]] +}}} + +See also the prerequisites for the L4Re-Fiasco.OC-patches distribution, +described in that distribution's documentation. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Source_Code --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Source_Code Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,47 @@ += Source Code Overview = + +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: + +|| '''Package''' || '''Description''' || +|| devices || a collection of device drivers and libraries || +|| landfall-examples || a collection of examples demonstrating the devices || + +In addition to the above, configuration files are provided for the example +programs in the `conf/landfall-examples` directory. + +== Device Support == + +A selection of devices are supported by this software. They are found within +the `pkg/devices` directory and are currently the following: + +|| '''Device''' || '''Description''' || +|| backlight || display backlight control || +|| cpm || clock and power management || +|| display || device-specific display control || +|| fb || framebuffer access || +|| input || input event delivery || +|| keypad || keypad/keyboard scanning || +|| lcd || LCD and other display peripheral support || +|| pwm || pulse width modulation support || +|| spi || serial peripheral interface support || + +Many device types provide the following kinds of support: + + * Server programs that regulate access to devices + * Client libraries that provide access to the server programs + * General library support for server programs to use + +In addition to the above, more general libraries found in the lib subdirectory +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, 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.) diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/System_Architecture --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/System_Architecture Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,103 @@ += 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. 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 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. + +Here is how the Ben NanoNote's framebuffer is supported by components: + +######## A graph showing the relationship between components. + +{{{#!graphviz +#format svg +#transform notugly +digraph nanonote_framebuffer { + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"]; + + fb_drv [label="fb-drv"]; + dev_cpm_jz4740 [label="dev_cpm_jz4740\nClock configuration"]; + dev_display_qi_lb60 [label="dev_display_qi_lb60\nDisplay control"]; + dev_backlight_spi_ili8960 [label="dev_backlight_spi_ili8960\nBacklight control"]; + dev_spi_jz4740 [label="dev_spi_jz4740\nBacklight communication"]; + + fb_drv -> dev_cpm_jz4740; + fb_drv -> dev_display_qi_lb60 -> dev_backlight_spi_ili8960 -> dev_spi_jz4740; +} +}}} + +######## + +And here is how the Letux 400's framebuffer is supported: + +######## A graph showing the relationship between components. + +{{{#!graphviz +#format svg +#transform notugly +digraph letux400_framebuffer { + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"]; + + fb_drv [label="fb-drv"]; + dev_cpm_jz4730 [label="dev_cpm_jz4730\nClock configuration"]; + dev_display_letux400 [label="dev_display_letux400\nDisplay control"]; + dev_backlight_pwm [label="dev_backlight_pwm\nBacklight control"]; + dev_pwm_jz4730 [label="dev_pwm_jz4730\nBacklight communication"]; + + fb_drv -> dev_cpm_jz4730; + fb_drv -> dev_display_letux400 -> dev_backlight_pwm -> dev_pwm_jz4730; +} +}}} + +######## + +Note that fb-drv links to the same generic JZ4740 LCD controller library in +both cases + +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. Device servers are connected +using capabilities (object references). + +Meanwhile, panel information is provided via a dynamically-loaded library: + +######## A graph showing the acquisition of panel information. + +{{{#!graphviz +#format svg +#transform notugly +digraph panel_information { + node [shape=rectangle,fontsize="13.0",fontname="Helvetica"]; + + subgraph { + rank=min; + fb_drv [label="fb-drv"]; + } + + paneldata [label="mips-jz4740-panel.txt\nLibrary details"]; + library [label="...\nLibrary with panel data"]; + + paneldata -> fb_drv -> library; +} +}}} + +######## + +This method of obtaining a configured library name in order to load it +dynamically is effectively equivalent to having a symbolic link identifying +the library referencing the desired, specific library to be used. Since the +"rom" virtual filesystem does not appear to support symbolic links, this +method is used instead. + +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. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/Tools --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Tools Sat Apr 13 19:28:39 2019 +0200 @@ -0,0 +1,66 @@ += Tools and Utilities = + +The `tools` directory contains a number of programs useful when developing +this software: + +{{{#!table +checkconfig.sh || initialises files used to control run-time linking for the + .. configured device +== +install.sh || installs the software in a L4Re source distribution +== +listlibs.sh || lists library modules for inclusion in .list files +== +makecontrol.sh || updates the Control file for a package directory with + .. details of the provided "virtual" packages employed by the + .. build system for dependency resolution +== +makefonts.sh || generate binary font files from source data +== +readfont.py || convert GNU Unifont source files to binary form +}}} + +== Identifying Library Modules == + +The `listlibs.sh` tool is intended to inspect an existing .list file, analyse +executable programs mentioned in that file that have already been built, and +to generate a list of shared libraries needed by those executables such that +the .list file describes all required modules for deployment. + +In the `l4` subdirectory of the L4Re source distribution, the tool is run as +follows: + +{{{ +$LANDFALL/tools/listlibs.sh conf/landfall-examples/$EXAMPLE.list mybuild +}}} + +(Here, `$LANDFALL` needs to expand to the location of this distribution +whereas `$EXAMPLE` indicates an example name.) + +For example: + +{{{ +~/L4/Landfall/tools/listlibs.sh \ + conf/landfall-examples/mips-qi_lb60-keypad.list mybuild +}}} + +This will output a list of modules for inclusion in the .list file. It can be +advisable to make this change to the .list file in the Landfall distribution +and to then install the file into the L4Re source distribution, potentially +using the install.sh script. + +At this point, it is important to remember that the `conf/modules.list` file +will need updating to include these new details. For example: + +{{{ +cp conf/landfall-examples/mips-qi_lb60-keypad.list conf/modules.list +}}} + +Finally, the command to build a payload can be run: + +{{{ +make O=mybuild uimage E=mips-qi_lb60-keypad-example +}}} + +This should consult `conf/modules.list` and update the contents of the +generated image to include any newly-added shared libraries. diff -r 3cf80b18e719 -r 1e9751847d33 docs/wiki/attachments/P5300454-800x600.JPG Binary file docs/wiki/attachments/P5300454-800x600.JPG has changed