README

   1 Qi Bootmenu System
   2 ==================
   3
   4  This is a set of simple shell scripts to cross compile everything
   5  that is needed in order to run an evas based bootmenu application
   6  with the framebuffer backend.
   7
   8  The ultimate goal is to build a complete initramfs (containing
   9  the bootmenu application) and kernel which can be flashed to your
  10  device.
  11
  12 Pre-Requirements
  13 ================
  14
  15  uClibc armv4tl cross toolchain
  16  ------------------------------
  17
  18  The boot system is uclibc based you can therefore _not_ use the
  19  openmoko toolchain. Instead you need to build your own cross
  20  compiler. This is however out of scope of this project.
  21
  22  I strongly recommend you to use a toolchain from the FWL project
  23
  24   http://www.landley.net/code/firmware/
  25
  26  It is relocatable and uses a gcc wrapper script to make the gcc path
  27  logic somewhat sane (if that's possible at all). It is currently
  28  the only tested and supported toolchain.
  29
  30  You can now either download a pre built uclibc toolchain from:
  31
  32   http://impactlinux.com/fwl/downloads/binaries/cross-compiler-armv4tl.tar.bz2
  33
  34  or build one from scratch with the following instructions:
  35
  36   1. Download and extract
  37
  38       http://impactlinux.com/fwl/downloads/firmware-0.9.10.tar.bz2
  39
  40   2. Build the cross compiler
  41
  42       ./download.sh && ./simple-cross-compiler.sh armv4tl
  43
  44   3. Copy the build/simple-cross-compiler-armv4tl directory to a
  45      place of your choice.
  46
  47  Now that you have a cross toolchain add it's bin directory to
  48  your $PATH.
  49
  50   cd simple-cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
  51
  52  Host tools
  53  ----------
  54
  55  The build scripts are currently not self contained they require
  56  various host tools. Please make sure you have the following ones
  57  installed:
  58
  59   git svn cvs lzop dfu-util autoconf automake libtool gettext
  60   mkimage
  61
  62 Building the boot system
  63 ========================
  64
  65  Environment setup
  66  -----------------
  67
  68  Make sure you have your cross toolchain somewhere in your $PATH,
  69  if this is not the case then add it.
  70
  71   cd cross-compiler-armv4tl/bin && export PATH=`pwd`:$PATH
  72
  73  By default the scripts assume 'armv4tl-' as toolchain prefix if your
  74  toolchain uses something different then set the $CROSS environment
  75  variable accordingly.
  76
  77  Configuring the build
  78  ---------------------
  79
  80  There are a few configuration settings which can be used to tweek the
  81  build system in various ways. They can be specified on the command line
  82  or via the top level config file which is sourced by the other scripts.
  83
  84  What follows is a short descritption of the most important ones:
  85
  86   $MACHINE has to be set to either GTA01 or GTA02 the latter is assumed
  87            the variable isn't specified
  88
  89   $STATIC  build qi-bootmenu statically and don't install shared
  90            libraries. This results in a slightly smaller + faster
  91            initramfs.
  92
  93  Building the initramfs content, kernel and bootloader
  94  -----------------------------------------------------
  95
  96  Building the whole system (all packages) including kernel and bootloader
  97  is as simple as executing the ./build.sh shell script. This will build
  98  a kernel (uImage-$MACHINE.bin) containing the whole boot system as an
  99  initramfs and a slightly modified version of the bootloader Qi (qi-*.udfu).
 100
 101  If you just want to rebuild an individual package then pass it's name as
 102  argument. For example if you just want to rebuild qi-bootmenu then run.
 103
 104   ./build.sh qi-bootmenu
 105
 106 Installing/Flashing the boot system
 107 ===================================
 108
 109  The last step should have built a kernel (uImage-$MACHINE.bin) and a
 110  bootloader (qi-*.udfu) these files can be flashed in the normal way as
 111  described in:
 112
 113   http://wiki.openmoko.org/wiki/Flashing
 114
 115  There are also two scripts included which should make this a straight
 116  forward process. Just run the following command and your newly built
 117  boot system should be installed.
 118
 119   ./flash-kernel.sh && ./flash-qi.sh
 120
 121 How it all works
 122 ================
 123
 124  The basic idea is to first install everything into a $STAGING_DIR and then
 125  selectively copy the required bits over to $ROOT_DIR. In the end the
 126  $ROOT_OVERLAY directory, which contains configuration files and other things
 127  which aren't generated by package builds, is copied over $ROOT_DIR.
 128
 129  After the packages are installed into $STAGING_DIR some paths which point
 130  to the host systems /usr/lib (because of the --prefix=/usr step) need to
 131  be changed. Without this the linker would search for the libraries in the
 132  hosts systems library directory.
 133
 134  Below are some descriptions of various parts of the build system.
 135  A big part of the code was actually taken from the FWL scripts that's why
 136  both system work in similar ways.
 137
 138   - ./sources/include.sh
 139
 140     Contains various environment variables which are needed in other scripts.
 141
 142   - ./sources/functions-fwl.sh and ./sources/functions.sh
 143
 144     Home of all shell functions which are used in the other parts of the
 145     system. These files are sourced from include.sh. functions-fwl.sh is
 146     mostly taken from the FWL project.
 147
 148   - ./download.sh
 149
 150     Downloads all the required source packages either with wget from
 151     some http/ftp server or uses a source code management system to
 152     check it out from a repository.
 153
 154   - ./sources/configs/miniconfig-{busybox,uClibc,linux}
 155
 156     Configuration files used for busybox, uClibc and the linux kernel
 157     in the miniconfig format.
 158
 159   - ./sources/patches/$PACKAGE-*
 160
 161     Patches for individual packages. They are applied within setup $PACKAGE.
 162
 163   - ./build.sh
 164
 165     Builds all or individual packages based on the files described in
 166     the next section.
 167
 168   - ./sources/sections/$PACKAGE.sh
 169
 170     Every package has a shell script with it's build instructions these
 171     files are sourced from ./build.sh.
 172
 173     They normally start with setupfor $PACKAGE. This extracts the
 174     source tarball to ./build/packages/$PACKAGE and applies all patches
 175     from ./sources/patches/$PACKAGE-*. The patched source is then copied
 176     over to ./build/temp-armv4tl/$PACKAGE where it is built.
 177
 178     The packages are then configured with something like:
 179
 180      PKG_CONFIG_PATH="${STAGING_DIR}/usr/lib/pkgconfig"
 181      CCWRAP_TOPDIR="$STAGING_DIR/usr"
 182      CFLAGS="-I$STAGING_DIR/usr/include"
 183      ./configure --prefix=/usr
 184
 185     This makes sure that the configure script and the compiler actually
 186     find the already cross compiled libraries and include files.
 187
 188     Packages are then installed into $STAGING_DIR.
 189
 190      make DESTDIR="$STAGING_DIR" install.
 191
 192     The parts which are actually needed are then copied over to $ROOT_DIR.
 193
 194     If the package is a library some paths which point to the host
 195     systems /usr/lib (because of the --prefix=/usr step) need to be
 196     changed. Without this it wouldn't be possible to link against the
 197     library because the linker would always be redirected to the
 198     hosts /usr/lib directory.
 199
 200     This is the case for libtool's *.la files in $STAGING_DIR/usr/lib
 201     and the pkg-config *.pc files in $STAGING_DIR/usr/lib/pkgconfig.
 202     The paths are changed by the two functions libtool_fixup_libdir
 203     and pkgconfig_fixup_prefix which are located in sources/functions.sh.
 204
 205     Finally the build directory is removed with
 206
 207      cleanup $PACKAGE
 208
 209   - ./initramfs.sh
 210
 211     This script copies the content of the $ROOT_OVERLAY directory which
 212     contains all the things which aren't generated by package build scripts
 213     over $ROOT_DIR. It then strips all unnecessary symbols from the binaries
 214     and generates a text file which can be specied as CONFIG_INITRAMFS_SOURCE
 215     during the kernel build. The kernel build system will then based on this
 216     file generate a gziped cpio archive and embed it into the kernel binary.
 217
 218   - ./package.sh
 219
 220     This script simply creates a tarball with the content of the rootfs
 221     directory. You can copy this to your Freerunner and chroot into it to
 222     test things out.
 223
 224 Changes to vanilla Qi
 225 =====================
 226
 227  The boot system also works with the unmodified version of Qi as found in
 228  the openmoko git repository.
 229
 230   http://git.openmoko.org/?p=qi.git
 231
 232  The patches which are applied are thus not strictly necessary but they have
 233  a few advantages over vanilla Qi.
 234
 235   - You won't have to mark your SD-card partition as not bootable via
 236     noboot-$MACHINE files
 237
 238   - It's slightly faster because after the first AUX press no further
 239     SD-card partitions are scanned Qi proceeds straight away with
 240     booting from NAND
 241
 242   - The NAND partition is ignored by the bootmenu because Qi will pass
 243     the required parameters on the kernel command line this reduces
 244     boot time because mounting an jffs2 file system is slow.