Howto build a custom ROM for the Zaurus.
Note: Following this howto has the potential of making a nice paperweight out of your Zaurus. Do this at your own risk. There are no guarantees that this will work. Whether or not you upgrade your filesystem, you'll have to do a hard reset during this process, and so you're going to lose all of your data, and any applications you've installed yourself. Now would be a good time to backup anything that you want to keep.
The Zaurus ROM is made up of two components:
- The Linux kernel
- The filesystem
Either one of these can be replace independently. This is really useful for doing such things as adding Wireless Extensions to the kernel without having to mess with any of the built-in applications.
There is a separate howto for building and installing a new kernel. Refer to The Kernel Howto for that documentation. This document concentrates mostly on creating a base filesystem. How to get a filesystem off of a ROM, modifying it and building it back into a filesystem image.
The following items are needed to build a ROM:
- A CF card 16MB or greater to be able to hold the new Flash ROM data with a msdos filesystem on it. Consult the Managing CF and SD Howto if you need to change the filesystem or clear it.
- A Linux box with root access (fakeroot can be used for some of the portions which need root, but not for things like formatting a CF card). This Linux box must be set up to compile applications for the Zaurus as given via the Compiler Setup howto if a new kernel is to be made.
2) Acquiring a ROM
Note: Now would also be a good time to fetch a copy of the original ROM image from the Sharp site, just in case the new filesystem / kernel doesn't boot. In that event, the original ROM can be used to flash back to the original state, and try again later.
More often then not a entire brand new ROM is not what is wanted, but one with just a few changed to add or remove a few things to some other already existing ROM. The first thing that is needed is the working filesystem from a current ROM. Skip to step 4 if a custom ROM created from the ground up is what you are looking for. If you are looking to modify an existing ROM keep reading.
There are several options on how to get a ROM to start with.
- Download the Official Sharp ROM from Sharp's website.
- Use an OpenZaurus ROM.
- Rip the ROM directly from a Zaurus.
The official ROM can be obtained from this location: http://www.myzaurus.com/ROMupdate3.asp
It can also be found on the Sharp Developer site which is in the links page.
Using an Open Zaurus ROM
Just as Sharp has ROM's that can be downloaded, Open Zaurus has its own set of ROMs that can be modified. See www.openzaurus.org for more information about OpenZaurus and the location of its ROMS.
Ripping the ROM
There is a ROM file on the Zaurus itself. Here are a number of ways to get at it.
If SSH is installed from a Linux box run:
$ ssh z 'cd /; tar cvvf - --exclude ./proc --exclude ./dev --exclude ./home . | gzip -9' > full_rootfs.tgz
If not, a CF card can be put in the Zaurus, and from a terminal run:
# cd /; tar cvvf - --exclude ./proc --exclude ./dev --exclude ./home . | gzip -9 > /mnt/cf/fullroot.tgz
Another way to rip the the initrd.bin (filesystem) is on the Zaurus run dd with the output file set in the cf or sd card:
dd if=/dev/mtdblock0 of=/mnt/cf/zaurus.rom
Then on the desktop you can mount it without haveing to worry about offsets.
mount -o loop -t cramfs zaurus.rom /mnt/zaurus
3) Getting The Filesystem from the ROM
There is an image of the ROM's filesystem called initrd.bin in any ROM file for the Zaurus. To get this file compile cramfs into the kernel on a computer running Linux (If it isn't do so already). If it is compiled and installed as a module run "modprobe cramfs" to install it. Then execute the following commands to mount the ROM in the local filesystem.
losetup -o 1835008 /dev/loop0 ospack.srom
mount /dev/loop0 /mnt/flashimage
(BTW, the magic number in the losetup line is 0x1c0000, the offset from the beginning of the flash image where initrd.bin is stored.) The rom contents are then available under /mnt/flashimage, and can be transfered from there to somewhere else with:
tar -cf - . | (cd /tmp/zaurusfilesys; tar xvf -)
Now that a copy of the filesystem has been obtained unmount the ROM.
4) Creating the Base for the new ROM.
Obtaining the Sharp base ROM
Sharp provides a basic root filesystem to play with which although it is missing a lot of the features of a standard filesystem, much more importantly although it does contain useful tools to build a filesystem, so we'll grab them.
Sharp's Filesystem: rootfs_20020204.tar.gz
Become root and extract the tarball, so that the files in the tarball are owned by root (fakeroot will do).
# tar xzvvf rootfs_20020204.tar.gz
Inside the rootfs directory should be: bin/, bootflag.txt, and, root_cramfs/. Inside bin/ is build.sh the script that turns the root_cramfs/ directory into a filesystem that the Zaurus can use. Because the include root_cramfs/ doesn't contain everything that the Sharp ROM has one can now replace everything in the root_cramfs/ directory with the ROM which was acquired in step 2.
Note: If the ROM was acquired from using the tar command make sure not to delete the following directories from the rootfs for the tar command will have missed them:
5) Go Wild with Modifications.
Now make whatever changes to the filesystem that are desired.
The root filesystem (mounted at /) is read-only ROM. Everything that's read-write on the Zaurus lives in ext2 filesystems mounted at /home and /dev. Everything else read-write that most people think lives outside /home (like /etc) is actually inside /home, and there's a symlink to them. For a good overview of how this all works see the System Layout howto.
More then likely items will want to be remove so other items can be put on it. To see a list of applications and there files go here.
Applications are distributed as *.ipk files which are nothing more then a tarball. For a better overview of ipk files see the ipk howto.
When coping files from an ipk into the new ROM (such as /usr/QtPalmtop.rom/bin/) make sure to create symlinks in the ".home_default.tar". (such as with /home/QtPalmtop/bin/) so that they will show up after /home has been mounted.
6) Building the ROM
In the bin directory of rootfs run the build.sh script to turn the rootfs/root_cramfs into a file that can be put on the Zaurus.
This command builds the initrd.bin file. The resulting initrd.bin must be less then 14811136 bytes (14MB+128KB). The default ROM at last check is 14798848 bytes. Not much room to spare!
You now have a new cramfs ROM filesystem! Only one thing left to do...
7) Installing the new ROM on the Zaurus
Now that there is a new "zImage" (kernel) and or "initrd.bin" (filesystem) they can flash them to the Zaurus. To do this all that has to be done is to follow the normal ROM upgrade howto using a CF card, but using these files instead of the ROM file, but they have to be named "zImage" for the kernel and "initrd.bin" for the filesystem. One really nice feature of this is that because you are not replacing the entire ROM it wont overwrite the flash utilities so even if something screws up the flash utilities are safe and you can safely move to a better ROM.