Qi Bootmenu System
==================
This is a set of simple shell scripts to cross compile everything
that is needed in order to run an evas based bootmenu application
with the framebuffer backend.
The ultimate goal is to build a complete initramfs (containing
the bootmenu application) and kernel which can be flashed to your
device.
Quick Start
===========
In theory all you need to do is run ./build.sh which should
create an uImage-GTA02.bin ready to flash to your device.
./build.sh && ./flash-kernel.sh && ./flash-qi.sh
Building the boot system
========================
Configuring the build
---------------------
There are a few configuration settings which can be used to tweek the
build system in various ways. They can be specified on the command line
or via the top level config file which is sourced by the other scripts.
What follows is a short descritption of the most important ones:
$MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
the variable isn't specified
$STATIC build qi-bootmenu statically and don't install shared
libraries. This results in a slightly smaller + faster
initramfs. This is enabled by default.
Building the initramfs content, kernel and bootloader
-----------------------------------------------------
Building the whole system (all packages) including kernel and bootloader
is as simple as executing the ./build.sh shell script. This will build
a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).
If you just want to rebuild an individual package then pass it's name as
argument. For example if you just want to rebuild qi-bootmenu then run.
./build.sh qi-bootmenu
Installing/Flashing the boot system
===================================
The last step should have built a kernel (uImage-$MACHINE.bin) and a
bootloader (qi-*.udfu) these files can be flashed in the normal way as
described in:
http://wiki.openmoko.org/wiki/Flashing
There are also two scripts included which should make this a straight
forward process. Just run the following command and your newly built
boot system should be installed.
./flash-kernel.sh && ./flash-qi.sh
How it all works
================
uClibc armv4tl cross toolchain
------------------------------
The boot system is uclibc based we can therefore _not_ use the
openmoko toolchain. Instead we need an uclibc based armv4tl
cross toolchain. Building one from scratch is however out of
scope of this project.
By default the scripts download a pre built toolchain from the
Aboriginal Linux project.
http://www.landley.net/code/aboriginal/
It is relocatable and uses a gcc wrapper script to make the gcc path
logic somewhat sane (if that's possible at all). It is the only tested
and supported toolchain.
If for whatever reason you don't want to run a pre built toolchain
you can run ./build.sh aboriginal which compiles one from scratch.
Altneratively you can also build one according to the Aboriginal Linux
documentation, make sure to add the toolchains bin directory to your
$PATH.
Build scripts
-------------
The basic idea is to first install everything into a $STAGING_DIR and then
selectively copy the required bits over to $ROOT_DIR. In the end the
$ROOT_OVERLAY directory, which contains configuration files and other things
which aren't generated by package builds, is copied over $ROOT_DIR.
After the packages are installed into $STAGING_DIR some paths which point
to the host systems /usr/lib (because of the --prefix=/usr step) need to
be changed. Without this the linker would search for the libraries in the
hosts systems library directory.
Below are some descriptions of various parts of the build system.
A big part of the code was actually taken from the FWL scripts that's why
both system work in similar ways.
- ./sources/include.sh
Contains various environment variables which are needed in other scripts.
- ./sources/functions-fwl.sh and ./sources/functions.sh
Home of all shell functions which are used in the other parts of the
system. These files are sourced from include.sh. functions-fwl.sh is
mostly taken from the FWL project.
- ./download.sh
Downloads all the required source packages either with wget from
some http/ftp server or uses a source code management system to
check it out from a repository.
- ./sources/configs/miniconfig-{busybox,uClibc,linux}
Configuration files used for busybox, uClibc and the linux kernel
in the miniconfig format.
- ./sources/patches/$PACKAGE-*
Patches for individual packages. They are applied within setup $PACKAGE.
- ./build.sh
Builds all or individual packages based on the files described in
the next section.
- ./sources/sections/$PACKAGE.sh
Every package has a shell script with it's build instructions these
files are sourced from ./build.sh.
They normally start with setupfor $PACKAGE. This extracts the
source tarball to ./build/packages/$PACKAGE and applies all patches
from ./sources/patches/$PACKAGE-*. The patched source is then copied
over to ./build/temp-armv4tl/$PACKAGE where it is built.
The packages are then configured with something like:
PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
CCWRAP_TOPDIR="$STAGING_DIR/usr"
CFLAGS="-I$STAGING_DIR/usr/include"
./configure --prefix=/usr
This makes sure that the configure script and the compiler actually
find the already cross compiled libraries and include files.
Packages are then installed into $STAGING_DIR.
make DESTDIR="$STAGING_DIR" install.
The parts which are actually needed are then copied over to $ROOT_DIR.
If the package is a library some paths which point to the host
systems /usr/lib (because of the --prefix=/usr step) need to be
changed. Without this it wouldn't be possible to link against the
library because the linker would always be redirected to the
hosts /usr/lib directory.
This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
The paths are changed by the two functions libtool_fixup_libdir
and pkgconfig_fixup_prefix which are located in sources/functions.sh.
Finally the build directory is removed with
cleanup $PACKAGE
- ./initramfs.sh
This script copies the content of the $ROOT_OVERLAY directory which
contains all the things which aren't generated by package build scripts
over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
during the kernel build. The kernel build system will then based on this
file generate a gziped cpio archive and embed it into the kernel binary.
- ./package.sh
This script simply creates a tarball with the content of the rootfs
directory. You can copy this to your Freerunner and chroot into it to
test things out.
Changes to vanilla Qi
=====================
The boot system also works with the unmodified version of Qi as found in
the openmoko git repository.
http://git.openmoko.org/?p=qi.git
The patches which are applied are thus not strictly necessary but they have
a few advantages over vanilla Qi.
- You won't have to mark your SD-card partition as not bootable via
noboot-$MACHINE files
- It's slightly faster because after the first AUX press no further
SD-card partitions are scanned Qi proceeds straight away with
booting from NAND
- The NAND partition is ignored by the bootmenu because Qi will pass
the required parameters on the kernel command line this reduces
boot time because mounting an jffs2 file system is slow.