Native compilation on the openmoko phone

Installing Gentoo base system on your Freerunner

Please report any problems you encounter. Approaches for other phones are probably similar.

Necessary things

At least 1.5 GB of space for rootfs (for Freerunner, this means either 2GB uSD card or external/network storage)

stage3 tarball: fetch stage3-armv4tl from a mirror out of  http://www.gentoo.org/main/en/mirrors2.xml

Portage tree snapshot: fetch portage-latest from a mirror out of  http://www.gentoo.org/main/en/mirrors2.xml

A working distribution on the target phone, for example flash it with SHR. Anything that can untar/edit files/chroot and has a fairly new kernel should be OK. Many stock distros tested.

A working kernel

Preparing files on rootfs

You can do this on another host than the target phone (it's usually faster).

Preparing your uSD card

If you don't want uSD card as rootfs, skip this section. Substitute /dev/mmcblk0(p1) with whatever device your uSD card appears as (see dmesg when you hotplug the card). Create partition on uSD card:

fdisk /dev/mmcblk0

You can create just a single partition. You will probably need swap but you can set up a swap file instead

Make filesystem on the partition

mke2fs -j -T small -L neo-root /dev/mmcblk0p1

-j stands for journal, so it makes ext3 instead of ext2

-T small is necessary for 2GB uSD cards and normal (non-squashfs) portage tree. Otherwise you run out of inodes when extracting portage tree

-L neo-root is partitions label, substitute to whatever you like

In case your sd card is recognized as scsi drive, partition will be something like /dev/sda1

Make swap In case you made swap as a partition

mkswap -L neo-swap /dev/mmcblk0p2

To activate the swap partition, use swapon:

swapon /dev/mmcblk0p2 

Extracting the base system

/media/card in the remainder of this section stands for mount point of your rootfs. If its on a card, it's best to umount it if it gets automounted using kde/gnome and remount it manually as root to make sure its mounted with sane flags.

mount -t ext3 /dev/mmcblk0p1 /media/card  

Stage3 tarball:

tar -xvjpf /path/to/stage3-armv4tl-*.tar.bz2 -C /media/card

Normal portage tree

Just extract it there:

tar -xvjpf /path/to/portage-latest.tar.bz2 -C /media/card/usr

Alternative: squashfs portage tree

For this, you need to have mkfs.squashfs installed. For very new kernel, you have to get it from CVS since you'll need the newest version for kernel to even mount it.

First extract portage tree somewhere:

tar -xjpf /path/to/portage-latest.tar.bz2 -C /tmp

then make squashfs image out of it:

mksquashfs /tmp/portage /media/card/var/portage.squashfs

And finally, clean up:

rm -r /tmp/portage

WARNING: About the following paragraph, Gentoo mirror maintainers generally don't like people frequently downloading portage snapshots off their servers. I'd suggest using a machine with normal portage tree synced normal way and creating squashfs off of it. Sorry about this tomboy, I couldn't reach you. ~jc

For later you can use this script to automatically fetch a clean portage-latest.tar.bz2 and have it merged with the openmoko overlay. This way you can avoid having layman (along with subversion and lots of cruft on your fr.

Set various settings

Here, vi will be used as a text editor, substitute with whatever you use (nano/mcedit/etc.) Set your phone's desired settings

Your zoneinfo (look into the dir and choose one that applies to you)

 cp /media/card/usr/share/zoneinfo/YOURZONE /media/card/etc/localtime

Set hostname

vi /media/card/etc/conf.d/hostname

Edit your fstab. Remember to put device files as they appear on the phone (for example /dev/mmcblk0 for uSD card)

vi /media/card/etc/fstab

Edit inittab and comment out unnecessary terminals (c3, c4, c5, c6, s0, s1). You should definitely comment out s0 and s1, else you get constantly respawning terminals. If you want a terminal on uart via debugboard and find out which device it is, please write your setting here. Be careful not to bind tty to your gsm modem :)

vi /media/card/etc/inittab

Locales should be set and regenerated after you boot into target OS. ~jc

Why to delay it for later ? anyway, if you will make an update glibc will be stuck on for more then an hour. ~yochai

Shouldn't 'locale-gen' be done later, after we chroot'ed to /media/card? ~khanku, bue

Set locals, it will save you time when you will update glibc :)

vi /media/card/etc/locale.gen
/etc/locale-gen

Swap file

If you don't use swap partition, you should set up a swap file.

First, create a zeroed file of certain size

dd if=/dev/zero of=/media/card/var/swap bs=1024 count=100k

where 100k means 100 MB swap file (100 000 * 1024 bytes)

Next, create swap on it

mkswap -L neo-swap /media/card/var/swap

Add it to fstab just as a regular swap, only instead of location of swap partition device, put location of the file.

Configuring the base system on the phone

Now boot some distro on your phone and mount your gentoo's rootfs.

If you have it on your uSD card or elsewhere where it gets automounted, umount it and remount it with clean flags.

Optional step, entering screen, this will allow you to close the connection to the phone without breaking your work:

screen -mS gentoo

Chroot into your gentoo's rootfs:

chroot /media/card

Update environment:

source /etc/profile && env-update

Set root password:

passwd

Enable sshd on startup:

rc-update add sshd default

Set up USB networking: here http://gentoo.mindzoo.de/index.cgi/wiki/USB_Networking

Remove consolefont from boot runlevel:

rc-update del consolefont boot

Section about profile? This should be done after booting into the target system. I'm not quite sure where to move this ~jc

It will be easy to create another page for stuff to do after your first boot but I don't see any reason, this way after the boot your system is ready for what-ever you need it. ~yochai

Choose the openmoko profile. In case you use layman you can do:

before you chose a profile you have to get the layout, there a two ways, manually: #you wont find the profile in there, get if from here:  http://overlays.gentoo.org/proj/embedded

or with layman:

USE="-apache2 -berkdb -dso -nls -perl -mysql" emerge dev-util/subversion app-portage/layman
layman --sync-all
layman -a openmoko
or the new repo: layman -a embedded-cross

and then

cd /etc
rm make.profile
ln -s /usr/portage/local/layman/openmoko/trunk/openmoko-target/profiles/openmoko make.profile

Note. The path can differ from one layman version to another. See  Installing Layman section in Gentoo Overlays: Users' Guide and  Layman section of Overlay page on Gentoo Wiki site.

Help! Help! Help! This is not a complete description. More information on how to setup the overlay is needed. See ticket:282 and ticket:287 for details. ~dememax

Finally, leave the chroot:

exit

Setting up Bootloader

When reaching this section, you should have your phone on with some stock distro running and your gentoo filesystem mounted somewhere.

Bootloader covers only u-boot as of writing. Please add Qi instructions if you ever do it.

Kernel configuration

Kernel and rootfs can be on seperate partitions. Best way probably is to keep kernel in NAND. Reason for this is that u-boot can't boot from some micro sd cards and definitely can't boot of network storage.

- Flash your kernel to NAND kernel partition via dfu-util.

In case you chose to load your kernel from the microSD you have to name it 'uImage.bin'.

Setting up U-boot

Get into your NAND u-boot prompt, as described here:  http://wiki.openmoko.org/wiki/Uboot#Accessing_the_bootloader_prompt

If you want to have gentoo as your primary system that boots up when you press power button, modify bootcmd. Else modify one of menu_n variables.

- Add rootfstype=ext3 and root=/dev/mmcblk0p1 on the kernel parameters line.

Now your system is ready. Reboot into it and enjoy. We recommend starting with emerging layman and using openmoko overlay.