Landfall

Annotated docs/wiki/Getting_Started

296:c4c278adb02a
159:42f877f29304
6 months ago Paul Boddie file changeset files shortlog Fixed I2C operations by reinstating IRQ binding to the main thread for I2C IRQs. cpm-library-improvements
paul@49 1 
= Getting Started =
paul@49 2 
 
 paul@49      3 
To use this software, it is necessary to first obtain the L4Re and Fiasco.OC
 
 paul@49      4 
source distribution:
 
 paul@49      5 
 
 paul@49      6 
[[http://l4re.org/download.html]]
 
 paul@49      7 
 
 paul@49      8 
With this unpacked, the patches from the L4Re-Fiasco.OC-patches distribution
 
 paul@49      9 
need to be applied. This patch distribution can be obtained from the following
 
 paul@49     10 
location:
 
 paul@49     11 
 
 paul@159     12 
[[https://projects.boddie.org.uk/L4Re-Fiasco.OC-patches]]
 
 paul@49     13 
 
 paul@159     14 
Instructions about applying the patches are provided in the patch
 
 paul@159     15 
distribution, as is a summary of the issues related to configuring and
 
 paul@159     16 
building this software. This document serves as a more detailed reference for
 
 paul@159     17 
the configuration and building of the Landfall components in particular.
 
 paul@49     18 
 
 paul@159     19 
<<TableOfContents(2)>>
 
 paul@49     20 
 
 paul@49     21 
== Configuring this Software ==
 
 paul@49     22 
 
 paul@49     23 
Some files may need to be adjusted for the device on which the software is to
 
 paul@49     24 
be deployed. A script is provided to check and update them:
 
 paul@49     25 
 
 paul@49     26 
{{{
 
 paul@49     27 
$LANDFALL/tools/checkconfig.sh $PLATFORM
 
 paul@49     28 
}}}
 
 paul@49     29 
 
 paul@49     30 
(Here, `$LANDFALL` needs to expand to the location of this distribution
 
 paul@49     31 
whereas `$PLATFORM` indicates a platform type.)
 
 paul@49     32 
 
 paul@49     33 
For example:
 
 paul@49     34 
 
 paul@49     35 
{{{
 
 paul@49     36 
~/L4/Landfall/tools/checkconfig.sh qi_lb60
 
 paul@49     37 
}}}
 
 paul@49     38 
 
 paul@49     39 
This configures the files for the Ben NanoNote. See the following file for a
 
 paul@49     40 
list of supported platforms:
 
 paul@49     41 
 
 paul@49     42 
{{{
 
 paul@49     43 
conf/landfall-examples/platforms.txt
 
 paul@49     44 
}}}
 
 paul@49     45 
 
 paul@49     46 
== Installing this Software ==
 
 paul@49     47 
 
 paul@49     48 
With the above patches applied, this software can be installed within the
 
 paul@49     49 
unpacked L4Re/Fiasco.OC distribution using a command of the following form:
 
 paul@49     50 
 
 paul@49     51 
{{{
 
 paul@49     52 
$LANDFALL/tools/install.sh $L4DIR
 
 paul@49     53 
}}}
 
 paul@49     54 
 
 paul@49     55 
(Here, `$LANDFALL` needs to expand to the location of this distribution
 
 paul@108     56 
whereas `$L4DIR` needs to expand to the location of the L4Re software.)
 
 paul@49     57 
 
 paul@49     58 
For example:
 
 paul@49     59 
 
 paul@49     60 
{{{
 
 paul@108     61 
~/L4/Landfall/tools/install.sh ~/L4/src/l4
 
 paul@49     62 
}}}
 
 paul@49     63 
 
 paul@147     64 
(The repository root of the L4Re/Fiasco.OC distribution typically contains a
 
 paul@147     65 
directory called `fiasco` and a directory called `l4`.)
 
 paul@49     66 
 
 paul@159     67 
== Obtaining Software Dependencies ==
 
 paul@159     68 
 
 paul@159     69 
As noted in the [[Prerequisites|prerequisites]] document, a number of other
 
 paul@159     70 
software dependencies are needed to be able to build the software. Various
 
 paul@159     71 
additional development tools and components are required, and these can be
 
 paul@159     72 
installed on a Debian system as follows (with appropriate privileges):
 
 paul@159     73 
 
 paul@159     74 
{{{
 
 paul@159     75 
apt-get install build-essential python unifont
 
 paul@159     76 
}}}
 
 paul@159     77 
 
 paul@159     78 
The idl4re distribution must be installed within the `l4` directory of the
 
 paul@159     79 
L4Re/Fiasco.OC distribution and the `idl` program built. This can be done as
 
 paul@159     80 
follows within that directory:
 
 paul@159     81 
 
 paul@159     82 
{{{
 
 paul@159     83 
hg clone https://hg.boddie.org.uk/L4Re/idl4re
 
 paul@159     84 
cd idl4re
 
 paul@159     85 
make
 
 paul@159     86 
}}}
 
 paul@159     87 
 
 paul@159     88 
See the idl4re documentation for more information.
 
 paul@159     89 
 
 paul@159     90 
The libipc package must be installed within the `l4/pkg` directory of the
 
 paul@159     91 
L4Re/Fiasco.OC distribution. This is purely a matter of obtaining the `libipc`
 
 paul@159     92 
directory from the Departure distribution. Within the `l4` directory, the
 
 paul@159     93 
package can be installed as follows:
 
 paul@159     94 
 
 paul@159     95 
{{{
 
 paul@159     96 
hg clone https://hg.boddie.org.uk/L4Re/departure
 
 paul@159     97 
mkdir pkg/departure-minimal
 
 paul@159     98 
cp -R departure/libipc pkg/departure-minimal
 
 paul@159     99 
}}}
 
 paul@159    100 
 
 paul@159    101 
Further integration of these distributions will hopefully make the
 
 paul@159    102 
installation of this software easier in future.
 
 paul@159    103 
 
 paul@49    104 
== Building the Software ==
 
 paul@49    105 
 
 paul@49    106 
With this software installed into the appropriate location, the instructions
 
 paul@159    107 
for building Fiasco.OC and L4Re can now be followed. Such instructions are
 
 paul@159    108 
provided in the L4Re-Fiasco.OC-patches distribution, but can be summarised as
 
 paul@159    109 
follows. For Fiasco.OC:
 
 paul@159    110 
 
 paul@159    111 
{{{
 
 paul@159    112 
cd fiasco
 
 paul@159    113 
make BUILDDIR=mybuild
 
 paul@159    114 
cd mybuild
 
 paul@159    115 
make config
 
 paul@159    116 
}}}
 
 paul@159    117 
 
 paul@159    118 
After interacting with the configuration dialogue:
 
 paul@159    119 
 
 paul@159    120 
{{{
 
 paul@159    121 
make -j
 
 paul@159    122 
}}}
 
 paul@159    123 
 
 paul@159    124 
For L4Re:
 
 paul@159    125 
 
 paul@159    126 
{{{
 
 paul@159    127 
cd l4
 
 paul@159    128 
make B=mybuild
 
 paul@159    129 
make O=mybuild config
 
 paul@159    130 
}}}
 
 paul@159    131 
 
 paul@159    132 
After interacting with the configuration dialogue:
 
 paul@159    133 
 
 paul@159    134 
{{{
 
 paul@159    135 
make -j
 
 paul@159    136 
}}}
 
 paul@49    137 
 
 paul@49    138 
As a consequence of building Fiasco.OC and L4Re, a payload can be generated
 
 paul@49    139 
and deployed for one of the examples provided by this software distribution.
 
 paul@159    140 
For example, in the `l4` subdirectory of the unpacked L4Re/Fiasco.OC
 
 paul@159    141 
distribution, a number of commands might be run.
 
 paul@49    142 
 
 paul@147    143 
First, a module list is copied from the `conf/landfall-examples` directory to
 
 paul@49    144 
`conf/modules.list`, this being the place where the build system obtains the
 
 paul@49    145 
details of the software to include in the payload.
 
 paul@49    146 
 
 paul@159    147 
{{{
 
 paul@159    148 
cp conf/landfall-examples/mips-qi_lb60-keypad-demo.list conf/modules.list
 
 paul@159    149 
}}}
 
 paul@159    150 
 
 paul@84    151 
The module lists provide details of essential programs and resources but may
 
 paul@84    152 
also require libraries if shared libraries are being used. The `listlibs.sh`
 
 paul@84    153 
invocation produces a manifest of required libraries for a given list of
 
 paul@84    154 
programs or modules. This manifest augments the module list provided.
 
 paul@84    155 
 
 paul@159    156 
{{{
 
 paul@159    157 
~/L4/Landfall/tools/listlibs.sh \
 
 paul@159    158 
  conf/landfall-examples/mips-qi_lb60-keypad-demo.list >> conf/modules.list
 
 paul@159    159 
}}}
 
 paul@159    160 
 
 paul@49    161 
Finally, the make invocation combines programs and libraries found in the
 
 paul@49    162 
`mybuild` directory and uses the indicated payload to construct, in this case,
 
 paul@147    163 
an example demonstrating use of the Ben NanoNote's keypad. Here, the `E`
 
 paul@147    164 
parameter corresponds to the `entry` line in the `conf/modules.list` file.
 
 paul@49    165 
 
 paul@159    166 
{{{
 
 paul@159    167 
make O=mybuild uimage E=mips-qi_lb60-keypad-demo-example
 
 paul@159    168 
}}}
 
 paul@159    169 
 
 paul@49    170 
== Deploying the Software ==
 
 paul@49    171 
 
 paul@49    172 
The resulting payload should reside in the created images directory and be
 
 paul@49    173 
deployed to the appropriate location on storage media used to boot the target
 
 paul@49    174 
device. For the above example, the following payload would be created:
 
 paul@49    175 
 
 paul@49    176 
{{{
 
 paul@49    177 
mybuild/images/bootstrap_mips-qi_lb60-keypad-demo-example.uimage
 
 paul@49    178 
}}}
 
 paul@49    179 
 
 paul@49    180 
More information about deploying payloads and booting devices is provided in
 
 paul@49    181 
the L4Re-Fiasco.OC-patches distribution's documentation.