Contents

Why?

Because now that the GP2X can use ethernet over USB and Wifi it’s pretty much a small form factor 200MHz ARM computer, and extremely portable at that. I’ve installed Gentoo on lesser machines. Also, I wanted an ultra portable box I could do programing with in whatever language I want, like Ruby or Lisp. But more generally, there is a vast array of software available to Gentoo that isn’t available for the native Linux of the GP2X. If I could get Gentoo on the GP2X (which considering it’s basically just a small ARM box, shouldn’t be too hard) then I’d be opening up a whole new and vast world of software for the GP2X.

As for why chrootable and not a full install? The GP2X firmware does a good job and is extremely compact (~20MB). Getting Gentoo down to that might be a trick. Plus, with the custom hardware, rolling my own kernel might be a bit of work. And it would also probably preclude me from using any GP2X specific software. A chrootable Gentoo environment gives me the best of both worlds. I can use the GP2X and assorted software as normal, but pop in an SD card, and suddenly I also have a Gentoo environment. The GP2X Linux ends up acting like a bootloader and an abstraction layer between the somewhat custom hardware of the GP2X and the Gentoo environment.

Getting the GP2X fully online

Note: On the computer side of things it is assumed you are running Gentoo, as I am, so some things may have to be changed accordingly

First, we have to get the GP2X properly online. Upgrade to the latest firmware (anything 2.* should do). Once the GP2X is upgraded, turn it on and go into the Settings->System . Turn on advanced options, USB Networking, set the IP to 10.1.0.2, and turn on at least Telnet and FTP.

On the computer end, you need to add some additional support to your kernel. You’ll need USB->USB Gadget Device support and from there ‘Ethernet Gadget (CDC)’ and ‘RNDIS’ support. Also, you need from USB->Networking: at least ‘Host for RNDIS’, and support for devices, so I went with ‘Simple USB Network Links (CDC)’ and ‘Netchip 1080’. Finally, you need from ‘Networking’ enough stuff to get iptables up and running and doing NAT (network address translation). Recompile your kernel. Reboot if needed. Load the appropriate modules if needed (and add them to /etc/modules.autoload).

Now connect the GP2X via USB to your computer. To see if the connection was noticed check dmesg. To try it out

ifconfig usb0 up 10.1.0.1

Then trying pinging the GP2X (10.1.0.2). If that works, you should then also be able to telnet and ftp to the GP2X.

If it fails, you may need to update your g_ether module on the GP2X. Follow this quick guide to update it and try again.

We’re almost there. We now have a LAN between your computer and the GP2X, but the GP2X doesn’t have net access. We need to setup the computer as a firewall that does NAT for the GP2X. On the computer run

iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
iptables -A INPUT -m state --state ESTABLISHED,RELATED -j ACCEPT
iptables save
echo 1 > /proc/sys/net/ipv4/ip_forward
/etc/init.d/iptables start

Now your desktop should do port forwarding for the GP2X. But the GP2X doesn’t know about it. So telnet onto the GP2X. We need to set it up for full internet access. Copy the contents of your /etc/resolv.conf to the GP2X’s /etc/resolv.conf (This lets it know what name servers it should use for DNS). Finally, we write a simple script you can leave in /root that sets up the routing.

net.sh

#!/bin/sh

route add default gw 10.1.0.1

Then on the GP2X

chmod a+x net.sh
./net.sh

Now the GP2X knows that all connections to the net should be sent to your computer, which is now set up to forward them to the internet. The info in /etc/resolv.conf tells the GP2X where to look for DNS info (changing names into IPs).

To test, on the GP2X

ping google.com

It should work. (net.sh will have to be run every time the GP2X reboots, you may want to make arrangements for that.)

Now, to make this setup more permanent on the computer side of things, we need to set up a few things. We can automate iptables by

rc-update add iptables default

And we can automate port forwarding by editing /etc/sysctrl.conf and changing

#net.ipv4.ip_forward = 0

to

net.ipv4.ip_forward = 1

Finally, we need to set up the usb0 connection.

ln -sf /etc/init.d/net.lo /etc/init.d/net.usb0

Then edit /etc/conf.d/net and add

config_usb0=( "10.1.0.1/24" )

Now you can

/etc/init.d/net.usb0 start

When ever you want to activate the connection to your GP2X. You can automate it with rc-update, but the connection may not work if the GP2X isn’t plugged in before net.usb0 is started. Your millage may vary. But it’s easily restartable :).

Preparing the media

We will be installing onto an SD card because the NAND on the GP2X is just about full, and we don’t really want to mess with it anyway. We will use the ext2 file system because it’s light, but provides all the features any UNIX like OS needs (unlike FAT which most glaringly doesn’t support file permissions or links).

First we format the SD card:

mkfs.ext2 /dev/sda1

/dev/sda1 being the devices for the SD card on my computer. Check first before formating that you aren’t formating your sata harddrive or something.

There are a few ARM Gentoo stage 3 tarballs floating around.

Since the GP2X runs glibc, I figured that we didn’t need the ultra embedded images with uclibc. So I opted for the ArmV4L (glibc) images from 2005.1. uname -a on the GP2X reveals it is in indeed an ARMV4L CPU.

I made a gentoo directory on the SD card (because you don’t want to mix GP2X things and Gentoo things) and put the stage3 tarball in it. Then I untared it.

Volia. That’s sort of it actually. You now have a Gentoo chrootable environment on an SD card. But we’re not really done yet. We need to initialize it, and get it ready for use, and there are a few more things to be done to the GP2X to make it ready. So don’t unmount that SD card yet.

The GP2X Linux is based around a limited version of busybox that lacks a few essential (IMHO) utilities. Among them is chroot. Thankfully I was able to dig up a copy of chroot for the GP2X. I grabbed it from the ‘GPE for GP2X’ package. Unfortunately it is statically compiled so it’s 2.3MB. Still, it does the trick. I put it online by it self at /resources/gp2x/chroot.static for use.

Note: I’m trying to get a dynamic version of chroot for the GP2X. I have the GP2X SDK installed and can cross compile for the GP2X. I tried using chroot from coreutils but I can’t get it to crosscompile properly. It still seg faults. It’d probably be better if I could track down the source to a stand alone version of chroot. Help would be appreciated.

I made a ‘gp2x’ directory on the SD card and tossed chroot.static in there (see, aren’t you glad you didn’t use the whole SD as the Gentoo root?). Now we are just about ready.

Networked File Systems

SD cards don’t have the hugest life spans. Lots of writes can reduce those lifespans. So it makes sense that if we can, we should farm out directories with lots of write to computers with real harddrives that can handle them. Also, if we have directories that we don’t often need but are huge, we should farm those out to. This is where networked file systems come in. We’re going to at least get /usr/portage to be on some other machine and just mount it over the network to our chroot Gentoo environment to save on space.

Samba for the GP2X

Get the Samba package for the GP2X from www.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,8,1478.

Now we install it to the GP2X’s root (‘firmware’). This will take up about 2.2 MB of space, which the GP2X’s NAND (where the firmware/Linux is installed) can spare. The package is a zip and the GP2X doesn’t have unzip, which is slightly annoying. They recommend turning the GP2X’s samba server on, mounting it, and unziping the packge to the root. This will work fine. I on the other hand unziped the packages to a directory on the SD card (‘samba’) and then put the SD card in the GP2X. Once in, I telneted onto the GP2X and copied all the files over to the root:

cp -r /mnt/sd/samba/* ./

(But that is slightly getting ahead of ourselves because we haven’t put the SD card in the GP2X yet and it doesn’t automount ext2 partitions, so if you are using this method you may want to jump ahead and then come back.)

To mount samba partitions the samba module has to be loaded on the GP2X

modprobe smbfs

Then you can mount directories as easy as

smbmount //10.1.0.1/portage /mnt/sd/gentoo/usr/portage

Again, slightly ahead of ourselves, but you get the idea.

Samba server Quickie

Now the GP2X can mount Samba file systems but we need to export some for that to be of any use. Install samba

emerge samba -va

On your computer and also add support for it to your kernel under filesystems->networked filesystems. You’ll need server support.

Then edit ‘/etc/samba/smb.conf’ and add something like the following

hosts allow = 10.1.0.

…

[Portage]
path = /usr/portage
comment = Portage
available = yes
browsable = yes
public = yes
writeable = yes

Then turn the sambe server on with

/etc/init.d/samba start

and automate samba server starting with

rc-update add samba default

If you want to use NFS on your computer to export /usr/portage, you can get the required NFS client package for the GP2X at archive.gp2x.de/cgi-bin/cfiles.cgi?0,0,0,0,42,1880.

Chrooting the Gentoo environment

Now we have everything in place to use our Gentoo environment. So, put the SD card into the GP2X. The GP2X doesn’t automount ext2 file systems, only FAT. That’s okay. Create a script to do it for you because it’s slightly a hassle.

/root/mount.sh

#!/bin/sh

mount /dev/discs/disc0/part1 /mnt/sd

Then run it. Now the SD card is mounted.

Now we have a Gentoo chroot ready for us and we can parallel the Gentoo Handbook for how to get into it.

Copy ‘/etc/resolv.conf’ into the chroot’s /etc (‘/mnt/sd/gentoo/etc’). You’ll only need to do this once. Now the chroot knows where to look for DNS info.

Next we copy ‘/lib/libiconv_plug.so’ into ‘/mnt/sd/gentoo/lib’. I’m not 100% sure why, but libiconv is some extension for glibc and since the GP2X uses it, if the chroot environment doesn’t use it, every command throws a harmless but annoying warning

ERROR: ld.so: object '/lib/libiconv_plug.so' from LD_PRELOAD cannot be preloaded: ignored.

Now the environment is ready to be chrooted. We’ll use a small script to automate the few steps we need.

/root/chroot.sh

#!/bin/sh

cd /mnt/sd/gentoo
mount -t proc none proc
mount -o bind /dev dev

/mnt/sd/gp2x/chroot.static /mnt/sd/gentoo /bin/bash

umount dev
umount proc

cd  /root

Finally, before chrooting, we’ll want to setup the remote portage directory.

smbmount //10.1.0.1/portage /mnt/sd/gentoo/usr/portage/

Now we can chroot to the environment.

/root/chroot.sh

Once in the environment, it’s common practice to

env-update
source /etc/profile

Now the environment is initialized and you can do what ever you want. We don’t really have to install anything or make the system bootable, because that’s what the GP2X firmware is for. We’re just hijacking it to jump start our more powerful environment.

Most likely you’ll want to install more software. That’s why we picked Gentoo, because it has more software available for it than the GP2X currently. Still, you’ll probably want to edit ‘/etc/make.conf’ and remove some flags, especially ones related to X.

/etc/make.conf

...
USE="-alsa -X -gnome -qt -qt3 -gtk -gtk2"
...

Also, before you can emerge anything, you’ll need to set up your profile:

ln -snf /usr/portage/profiles/default-linux/arm/ /etc/make.profile

Now you are ready to emerge software.

Note: Software installation is currently not recommended at this point. Compilation takes place at ‘/vat/tmp/portage’ which is on the SD card. This will start to take it’s toll on the SD card. I attempted to get /var/tmp/portage to also be a Samba mount and succeeded as far as I could mount it remotely, however, portage complained it could not chmod the directory appropriately and thus failed. Until I can get this working I’m not too eager to emerge much software and would recommend you also take it easy until you can successfully get /var/tmp/portage remotely mounted. Suggestions would be appreciated.

Crossdev

Another way to install software on the GP2X is to cross compile it, which is compiling it on another computer, for ARM, and then package it (yes portage supports binary packages). There are some difficulties which I’ll outline, but this method should be possible at least.

You should start by reading www.gentoo.org/proj/en/base/embedded/cross-development.xml. It’s a comprehensive run down of crossdev, a Gentoo app to help setup a cross compiling environment. It’s what you would use to get the tools you need to cross compile for the GP2X. It also goes over packaging something for another computer for easy deployment. It’s required reading.

I’ve started playing around with this so I have some pointers for anyone else looking to try it. The GP2X funs Linux 2.4.25, but the closest matching kernel in portage is 2.4.26-r1. Use it. The Linux chroot has glibc-2.3.5 but that doesn’t work with crossdev, go with 2.3.6-r5 at the least. The chroot also has gcc 3.4.4, but that again doesn’t play nice in crossdev, use gcc-3.4.6-r1 instead. My final crossdev command looked like

USE="-*" crossdev -v --libc 2.3.6-r5 --gcc 3.4.6-r1 --kernel 2.4.26-r1 --ex-gdb --target arm-unknown-linux-gnu

When setting up your ‘make.conf’, the architecture of the GP2X you’ll want to use in CFLAGS for -mcpu and other tuning arguments is ‘arm920t’.

I was able to get crossdev installed, but using xmerge, I was unable to then compile anything, instead I kept getting C compiler cannot create executables. errors.

Also, the crossdev solution seems slightly more geared towards more embedded devices where you will be creating a whole environment in one go and then doing something like flashing it onto the device. It feels less suitable for package by package software installation (by proxy) for the GP2X. Partly because you’ll have to keep track of all the dependencies installed and package those too and install then on the GP2X. Another problem that then creeps up is that since hte GP2X has a Stage3 install, it already has lots of software, but the crossdev environment has none, so it will compile newer versions of everything for it self. It does seem to start to become a bit of a hassle and mess.

Conclusion

Well, I got a chrootable Gentoo environment setup on the GP2X. That’s pretty impressive. The only hitch is that I currently don’t feel comfortable installing (emerging) software due to the adverse effects it might have on my SD card. But there are options from here. You could set up a cross compilation system, fairly easily accomplished with crossdev, and cross compile packages for the GP2X on a computer and then just install the precompiled packages. This may end up being more effort than it’s worth, see above. Also, research further on how to get portage to play nice with samba mounted /var/tmp/portage.

Also, as an after thought, you might want to take the SDL libs for the GP2X and untar them in the chroot environment and emerge –inject SDL. It’s possible you might be able t install some SDL applications then. Or at the least you should be able to write your own.

Finally, I hope this ends up being a useful tutorial/howto for anyone out there interested in any of the topics covered.

References