View source for Building OpenMoko 2007.1 from scratch

From Openmoko

Jump to: navigation, search

You do not have permission to edit this page, for the following reasons:

  • The action you have requested is limited to users in the group: Administrators.
  • You must confirm your email address before editing pages. Please set and validate your email address through your user preferences.

You can view and copy the source of this page:

Template used on this page:

Return to Building OpenMoko 2007.1 from scratch.

Personal tools


WARNING: This is still a preliminary version, which will take some more days until it has all the updates.

WARNING: To build OpenMoko, your machine needs to have at least 512 MB physical RAM and some swap space. Some gcc instances will well grow beyond 300MB of size (e.g. while compiling many files at once, e.g. for busybox). If even a part of the data which gcc allocates is in swap, about 99.9% of CPU time is wasted to wait for the memory be paged in and out RAM which means that the compilation time will be unreasonably long with only 256 MB of RAM.

Note: busybox can by built with less RAM by disabling CONFIG_BUILD_AT_ONCE, but the binary may be less optimized

This is a guide describing how to set up a running OpenMoko system from scratch.

If you just want to run OpenMoko applications on your PC, just perform the "Obtaining OpenMoko SVN tree" step below and then go to How to run OpenMoko Apps on PC. If you want to autoinstall all required tools and resources, consider using MokoMakefile -- script developed by Rod Whitby.

MokoMakefile is an automated front end for the commands which we execute manually here, so when using MokoMakefile, the end result will be the same, but you do not have do the download, extraction and setup OpenEmbedded by hand as described here, which can save quite some time because each step takes a while before you can check that it worked and run the next command.

Do not treat this as a linear script! There are various configuration items you need to set (or skip, as it may be), operations that depend on how your host(s) is/are set up, and also on the hardware revision of the target platform (i.e., the phone).

Instead, look at each step, read the instructions, copy and paste what makes sense for you, and adapt what you disagree with. Links to original and background material in the Wiki are included wherever useful.



The build process may spread over multiple machines. They have the following roles:

build host, with quick access to the files and CPU power. Must have Internet access.
lab machine connected to the debug board (serial and JTAG) and to USB on the Neo (since this will probably be just a single machine, the roles are not further divided)
machine with a USB-attached SD/MMC card reader

All machines are assumed to share the same filesystem layout. At the beginning of each of the sections below, the respective role is indicated. "(all)" is for settings that apply to all machines, or that - for simplicity - can be applied to all of them.

Directory layout

(Roles: all)

$OMDIR (/home/moko)	base directory for the whole tree
  openmoko/		files from OpenMoko subversion (SVN) repository
  openembedded/		files from OpenEmbedded (OE) Monotone repository
  sources/		cached downloads of OE
  build/		OE build directory

Environment variables

(Roles: all)

For simplicity, we just set these environment variables on all hosts involved. If you're not comfortable with this, feel free to weed out the ones you don't need.

Our base directory (configure this for local arrangements):

export OMDIR=/home/moko

The search path for BitBake files. Note that the order is of vital importance.

export BBPATH=$OMDIR/build:$OMDIR/openmoko/trunk/oe:$OMDIR/openembedded

Build host prerequisites

(Role: BUILD)

There must be at least 7 GB of free space on $OMDIR.

In addition to the traditional development tools (gcc, patch, etc.), the following packages must be installed on the build host:

version control system used by OpenMoko and others.
patch management system used by the Linux kernel and others
version control system used by OpenEmbedded. Use version 0.31/0.32 or newer. Monotone is not available pre-built for all Linux distributions. Get the statically linked binary from - building from source is difficult and even release tarballs (e.g. 0.36) may have C++ build issues with GNU C++ version 4.1 or newer ("no matching function call") which may be non-trivial to fix.
the OE build process wants this
this too
version control system used by the Linux kernel and others. Do not confuse this with the "GNU Interactive Tools"

Furthermore, the following package can be installed optionally:

Python just-in-time compiler. Speeds up OpenEmbedded builds (with BitBake) considerably. Strongly recommended.

Distro Specific Software Installation

Gentoo users can obtain all this with (note that, at the time of writing, Monotone 0.32 isn't available without setting the ~x86 keyword):
echo 'dev-util/monotone ~'`readlink /etc/make.profile | awk -F / '{print $6}'`\
emerge -u subversion quilt monotone diffstat texi2html dev-util/git psyco
Other Distos
Instructions for installing prerequisites in other distributions

Lab host prerequisites

(Role: LAB)

The following package must be installed on the lab host:

a simple communications program for the serial port

Gentoo users can obtain this with:

emerge -u xc

Note that similar communications programs, such as "cu" or "minicom", may be used as well.


(Roles: LAB, CARD)

We make the following assumptions about hardware setup and devices:

  • the serial console of the Neo phone is connected to /dev/ttyS0 on LAB (see Debug_Board)
  • the JTAG wiggler is connected to /dev/parport0 on LAB. See Debug Board and Connecting_GTA01Bv2_with_Debug_Board
  • cards inserted in the SD/MMC card reader appear as /dev/uba on CARD and can be mounted on /mnt/tmp (we'll specify the mount point explicitly, so the directory has to be there, but we don't need to specify the mount point in /etc/fstab). If in doubt,
mkdir -p /mnt/tmp

Obtaining Sources and build system

OpenEmbedded build: initial downloads

First, we obtain a snapshot of the OpenEmbedded-based tree used by OpenMoko, plus the OE build tool called BitBake.

Obtaining OpenMoko SVN tree

(Role: BUILD)

Obtain the latest revision of the OpenMoko tree. Unfortunately, at some places, "current" versions of upstream packages may get included, thus the build may still fail. If it does, you may wish to inform the authorities.

The checkout should take about 45 minutes over an Internet connection with a round-trip time to of 350 ms, given a data transfer rate of around 100kB/s.. It downloads about 370MB of data:

svn co openmoko

Installing BitBake

(Role: BUILD) BitBake is the build tool of OE. (This is quick.)

WARNING: If you run with root privileges, these instructions will cause bitbake to install itself under /usr in the area usually reserved for package managers. If run as user, it needs write permisson to /usr/local/{bin,lib} and it needs to create /usr/share{,doc)/bitbaker (the latter also are under /usr). There is no uninstall command either.

Note: If you use MokoMakefile, the Makefile automatically selects the correct bitbake version and it does not install it, it is only used locally: It creates ./setup-env, which can be sourced to manually use the local bitbake. Note: BitBake 1.8.8 requires sqlite-3.3 or later.

If building 2007.1 (old version), get version 1.6:

svn co bitbake

If building 2007.2 (new, current version), version 1.8.8 is recommended:

svn co bitbake

and install it:

cd bitbake
./ install
cd ..

Obtaining OpenEmbedded snapshot

(Role: BUILD)

Obtain a snapshot of the Monotone repository of OpenEmbedded, then update it to the latest version, and finally check out our "known to be good" revision. We extract things into $OMDIR/openembedded. is about 140 MB.

mtn pull
mtn checkout \
  -r e2dbb52fe39df7ef786b6068f6178f29508dfded openembedded
NOTE: For advanced users: if you ever want to update to the latest version of the repository, you would do a "pull" (see above), followed by:
cd $OMDIR/openembedded && mtn update

NOTE: For users of newer versions of monotone: you may need to migrate the database you downloaded with the wget command. You will know that this is necessary because the first mtn command shown above will fail with a warning indicating that you need to migrate the database. To do so, type:
mtn db migrate

Set up the directories for the cache of upstream files and all material related to local builds, then put our configuration file there (see also OpenMoko#Setting_up_an_OpenMoko_SDK):

mkdir -p sources build/conf
cat <<EOF >build/conf/local.conf
MACHINE = "fic-gta01"
DISTRO = "openmoko"
BUILD_ARCH = "`uname -m`"

OpenEmbedded build: fixes

(Role: BUILD)

There are unfortunately some problems in the build process. The following fixes work around them:

cd $OMDIR/sources
mkdir -p ../build/tmp/stamps/armv4t-linux
  • upstream moves old packages away, gratuitously breaking downstreams
touch ../build/tmp/stamps/armv4t-linux/js-1.5-r0.do_fetch
  • mirror has vanished
touch ../build/tmp/stamps/armv4t-linux/samba-3.0.14a-r15.do_fetch
  • ghastly patch with CRLF and trailing blanks
perl -pi.orig -e 's/ *$//;s/\r//g' \


OpenEmbedded build

(Role: BUILD)

openmoko/trunk/oe/conf/site.conf expects the OpenMoko-specific OE packages in $OMDIR/oe

ln -s openmoko/trunk/oe ./oe

We're now ready to run the build. This will take a while.

cd $OMDIR/build
bitbake openmoko-devel-image

Note that the build will stop several times to ask for SVN access and whether to accept certificates. If you're not quick enough to respond, the underlying session may time out. In this case, just restart "bitbake openmoko-devel-image" and it will pick up from where it left off.

NOTE: As of 16 September 2007, subversion updates of uboot and the kernel are attempted on each rebuild attempt, even if both were already successfully built in the previous built attempt. Even if no changes are found during svn update, uboot and kernel are recompiled, which increases the time per respin.

The whole build process involves numerous downloads, takes about 7 hours on an Athlon 64 3200+ (about 1.5h of delays were caused by not working properly during this test run), and ends with a message like this:

Build statistics:
  Attempted builds: 4


Flash boot loader into NAND

(Role: LAB)

As a first step, we transfer the u-boot bootloader into NAND Flash, through the JTAG interface. We use JTAG, since this is the most basic way for doing this, ensuring that we only depend on as little to work on the Neo as possible.

For this, the u-boot image for the right board version and the desired build date must be chosen. E.g., an image built for a gta01bv2 board on February 3, 2007 at 13:40:41 would be called u-boot_nand-gta01bv2-20070203134041.bin

The name is composed as follows:

the name of the component
it is it be loaded from NAND (not directly from RAM, see also Bootloader#Using_JTAG_to_boot_from_RAM)
the hardware revision of the board
the build date and time
this is a binary suitable for flashing/loading

If this is the first build, there will only be one image for each board version, thus we can use wildcards. Change the gta01bv2 below to gta01v3 or gta01v4, if necessary.

See also: Sjf2410-linux

cd $OMDIR/build/tmp/deploy/images

( echo 0; echo 0; echo 0; echo 3; ) |
  ./sjf2410 -b -f `echo u-boot_nand-gta01bv2-*.bin`

This will take approximately 12 minutes.

Copy kernel and root FS to microSD card

(Role: CARD)

There are several ways to provide the Neo with its kernel and the root file system. (See Bootloader for some of them.) The most self-contained way is to put everything into NAND Flash. To transfer the files to the Neo, we first place them on the microSD card.

Memory cards, including microSD, usually come pre-formatted with VFAT. We prefer ext2 (e.g., because we may want to store a real Linux file system on the card as well). The following steps are needed to convert the card from VFAT to ext2:

sfdisk -c /dev/uba 1 83
mke2fs -m0 /dev/uba1
tune2fs -c0 -i0 /dev/uba1

Next, we copy the kernel uImage and the root file system image to the card. As discussed in the previous section, we can use wildcards if this is our first build.

cd $OMDIR/build/tmp/deploy/images
mount /dev/uba1 /mnt/tmp
cp uImage-2.6-moko7-r1-fic-gta01-*.bin /mnt/tmp/uImage
cp openmoko-devel-image-fic-gta01-*.rootfs.jffs2 /mnt/tmp/rootfs.jffs2
umount /mnt/tmp

Now, insert the microSD card into the Neo, but don't power it on yet. (If you did anyway, don't worry. We'll power cycle it later.)

Serial console

(Role: LAB)

We use a serial console connecting through the debug board. This example uses "xc", which is a small and simple communications program. Many people prefer "cu" or the considerably more bloated "minicom", which will work as well.

  • Prepare xc configuration
cat <<EOF >$HOME/xc.init
set bps 115200
  • Connect to the target
xc -l /dev/ttyS0 -t

Start the Neo and enter the boot prompt

(Role: LAB)

Our first interaction with the target. If this doesn't work, please check that the debug board is connected properly to the serial port.

Disconnect power and USB from the phone, wait a couple of minutes, then connect power. You may have to press and hold the power button on the Neo for a few seconds to turn it on. The power button is located next to the USB port.

Some people have observed stability issues if the device was reset without power cycling or if USB was not disconnected when power cycling, yet details of what is really happening aren't very clear yet.

On the serial console, a message like this should appear:

U-Boot 1.2.0 (Feb  3 2007 - 13:07:21)
Press any key to enter the boot prompt:
GTA01Bv2 #

Note that the boot prompt changes with the hardware revision you have. If the message does not appear after a few seconds, try power cycling again.

If xc responds to pressing a button with "Verify that you are trying to use a valid and operational tty port." the port may be stuck, waiting for DCD to be asserted. The quickest way to get out of this situation is to disconnect the serial cable from the debug board, run the following command

while ! stty -F /dev/ttyS0 clocal; do : ; done

stick something metallic, e.g., a paper clip or a screwdriver, into the plug on the cable, and keep on fumbling with it until DCD gets set and the loop above stops spitting out error messages.

Flash kernel and root FS into NAND

(Role: LAB)

We now load the kernel and the root FS from the microSD card into memory and subsequently transfer them to NAND Flash. All this is done by entering commands at the boot prompt.

Each time we want to write new data to the NAND Flash, we first have to erase the previous content. We do this individually for each partition. While it would also be possible to erase some or all relevant partitions in one step, this would require the user to look up addresses from the partition table and to perform calculations which are inconvenient at best.

See also: U-boot

  • Initialize the SD/MMC interface. The "Product Name" shown will be just binary garbage. This is expected behaviour.
GTA01Bv2 # mmc
  • Load the uImage file into memory. "ext2load" stores the number of bytes read as a hexadecimal number in the environment variable "filesize".
GTA01Bv2 # ext2load mmc 0 0x32000000 uImage
  • Erase the kernel partition and write the uImage from memory to NAND Flash
GTA01Bv2 # nand erase kernel
GTA01Bv2 # nand write.e 0x32000000 kernel ${filesize}
  • The root file system is next. We need to specify the correct size, which is shown at the end of "ext2load", e.g., "0x1608000)" in this case:
GTA01Bv2 # ext2load mmc 0 0x32000000 rootfs.jffs2
23101440 (0x1608000) bytes read
GTA01Bv2 # nand erase rootfs
GTA01Bv2 # nand write.e 0x32000000 rootfs ${filesize}

Configure the boot loader

(Role: LAB)

Last but not least, we have to set up the boot loader to automatically boot from Flash. For this, we use the default environment settings, which we obtain by erasing the old content of the environment, and letting u-boot restore the settings after a restart.

Before touching the environment, you may have to update the environment offset. Please see Migration_to_bad_block_tolerant_builds#Partition_sizing for details. (We may simplify this particularly awkward and error-prone procedure in the future.)

  • First, remove erase the old environment:
GTA01Bv2 # nand erase env
  • We reset to force the boot loader to use the default settings.
GTA01Bv2 # reset

Wait until the "U-Boot [...]" message, then hit a key. It will display

*** Warning - bad CRC or NAND, using default environment
  • Re-generate the partition information in the environment variable "mtdparts":
GTA01Bv2 # dynpart
  • Save the restored settings in NAND
GTA01Bv2 # saveenv
  • Power cycle to boot the Neo (see remarks above)


Congratulations ! You've just completed level 1 of the OpenMoko adventure.