Boot setup

This guide assumes you have got the operating system of choice at the ready.

Partition your SD card

This is an optional step. It may be a good idea to set up multiple partitions/slices on your SD card - reasons include wanting to include a separate first partition for use on Windows, having a swap partition, or separating your kernel image from your root filesystem in case of filesystem corruption.

If you do want to slice your SD card into several partitions (see Setting up mutliple-partition SD cards), you can use the cfdisk command-line tool on the Pandora to create a partition table, or you can also download and use the graphical tool gparted.

Note that - as of Zaxxon HF5 - the Pandora firmware doesn't have a command to format FAT partitions, so if you want to use the FAT/ext2/swap - scheme, you'll have to format the first partition on another system later on (under Windows, use the Disk Management tool).

Using cfdisk

Assuming your card is in the left slot:

sudo cfdisk -z /dev/mmcblk0

WARNING: mmcblk0 will not necessarily be the left slot. It's the first card that the system recognizes, which is usually the left slot (but not if you inserted an SD into the left slot after you had one in the right slot, for example). Please make sure before you do anything dangerous e.g. use 'mount' to see what filesystems you recognise are mounted from where.

cfdisk -z starts off with a clean partition table - if you want to see what's set up currently, use cfdisk /dev/mmcblk0.

Use only primary partitions (so you're limited to four slices).

Using gparted

Download the gparted PND and install it. Note: this generally requires having a second SD card to install it to, though it should be possible to install it to the /pandora folder in your filesystem root, which will install it to NAND.

Find the program under 'System' in the menu and launch it. WARNING: It will start off pointing at /dev/mmcblk0 which is usually your left slot, but may not be. You can switch between the two card slots (if you have a card in each) and deduce which is which from the graphical display and the partition labels, but please be sure before applying any changes. Selecting 'information' from the right-click menu will also show you where each partition is mounted on the root filesystem, if it is currently mounted.

If the system has automounted the existing partition it'll show as locked and you'll need to unmount it using the right-click menu before you'll be able to change it. In this case, you'll probably want to delete it and create new partitions. Note that whatever partition your end up installing your boot/autoboot.txt to must be either ext2 or FAT, but you have a freer choice of filesystems to use on other partitions.

Once you've decided on your partitions and marked up the changes you'll need to apply them. Use the Apply All Operations menu item from the Edit menu. Then sit back and wait as it repartitions and reformats your card.

Format SD card

If you didn't use gparted to partition and format your card, you need to format your SD card to have at least an ext2 partition; ext3 also works^[1] and is more reliable^[2]. You can have additional paritions, such as swap partition, as well if you like.

Using the command line

Take care with using these command line tools, to be certain you are accessing the correct device. They will not ask you and will DESTROY any data on the device. This command will replace an existing partition with an empty EXT2 formatted filesystem (this includes the single FAT partition most SD cards come shipped with). Assuming /dev/mmcblk0p1 for your SD device (left slot, first partition), LABELNAME for the partition:

mkfs.ext2 -L LABELNAME /dev/mmcblk0p1

or

mkfs.ext3 -L LABELNAME /dev/mmcblk0p1

If you run into problems with formatting the SD card, try unmounting it first:

sudo umount /media/[LABELNAME of SD card]

Copy and boot

Copy the files to your SD card

Navigate (cd) to the directory with the .tar.bz2 file you just downloaded (or made) and do:

sudo tar -xvjf <tarfile>.tar.bz2 -C <SD card>

If you're doing this on your Pandora, <SD card> is something like /media/mmcblk0p1 (first SD card slot on Pandora). On Ubuntu it would be something like /media/disk if it has no label. You can also try using GUI tools for this, but I didn't have very good luck with them.

OR copy your firmware from the NAND to the SD card

The following will ask for your password. All the operations need root permissions so I thought it would be wasteful to sprinkle sudo to everything. We will bind mount the root fs to an alternative location ("/mp"), under which other filesystems mounted under root (like the kernel virtual filesystems /proc and /sys, and your SD card.) wont be visible. This allows us to take a live copy of the NAND contents to the SD filesystem.

sudo su
mkdir /mp
mount --bind / /mp
cp -va /mp/* /media/<SD card>
umount /mp
rmdir /mp
exit

Set up your boot.txt

Create a new file called boot.txt (or autoboot.txt if you want to boot automatically) and copy and paste the text below. Copy that file to the root of the root of the SD card.

boot.txt (from the official firmware site)

setenv bootargs root=/dev/mmcblk0p1 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ext2load mmc 0 0x80300000 /boot/uImage-3
bootm 0x80300000

Note: depending on firmware version kernels might be at several, sometimes multiple locations, so you have to choose one:

• /boot/uImage-3 - the default 3.2 kernel (recommended)
• /lib/boot/uImage - alternative location of 3.2 kernel on certain older firmwares
• /boot/uImage - the old 2.6 kernel

Be aware though that this boot.txt assumes you have formatted your card with ext2 and loads the kernel off the SD card. It is possible to boot the kernel from NAND with following boot.txt

setenv bootargs root=/dev/mmcblk0p1 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ubi part boot && ubifsmount boot && ubifsload ${loadaddr} uImage && bootm ${loadaddr} && boot

However this is not recommended because kernel modules on SD card will likely be not compatible with kernel on NAND.

Both boot.txt's assume you are booting from the left SD card slot, first partition. You can change "mmcblk0p1" to "mmcblk1p1" if you want to boot from the right slot (but boot.txt must still be on a card on the left slot). Note: If you chose ext3 instead of ext2, the second line still starts with ext2load. There is no ext3load.

Setting up mutliple-partition SD cards for booting

It is possible to have several partitions on the SD card and boot from one of them. E.g. if you have three partitions on the card like this:

• Partition 1: FAT
• Partition 2: ext2 (where the rootfs should be placed)
• Partition 3: swap

How it's done:

1. Put uBoot's boot control files "boot.txt" and/or "autoboot.txt" into the root of the first partition of the card (FAT partition in this example)

2. Make "boot.txt" and "autoboot.txt" point U-Boot to the partition, which holds the root file system of your Linux system. This would be parition 2 in this example (ext2 FS). This is done using the "root" parameter of setenv.

3. Make "boot.txt" and "autoboot.txt" point U-Boot to the correct location to boot your kernel from. This kernel location can be any FAT or ext2/3/4 partition on the SD card. The uBoot commands "fatload" and "ext2load" with their parameter "mmc x:y" are repsonsible for loading the kernel. Choose the command, which addresses the file system the kernel is located on and make sure to correctly adapt the values x and y.

This common example boots the kernel from the FAT partition (then this is a "boot partition"), and uses the ext2 file system as root FS:

setenv bootargs root=/dev/mmcblk0p2 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
fatload mmc 0:1 0x80300000 uimage
bootm 0x80300000

If you put the kernel into the root file system's /boot directory, the second line would be different:

setenv bootargs root=/dev/mmcblk0p2 rw rootwait vram=6272K omapfb.vram=0:3000K mmc_core.removable=0
ext2load mmc 0:2 0x80300000 /boot/uImage
bootm 0x80300000

Note:

For "root=" kernel argument, slot numbering begins at 0 (0 is left SD slot, 1 is right SD slot) and partition numbering begins at 1!

For "mmc x:y" agrument of the fatload/ext2load commands, x is the card number (0 is left slot, 1 is right slot), y is the partition number, beginning at 1(!).

Recommendation:

Put the kernel into another partition than the root FS is located. Reason: In case the root FS partition is flagged "inconsistent" after a system crash or sudden SD card removal, uBoot won't be able to boot from that partition anymore. But the file system cleanup routines can only be run, once the kernel has been booted. Hence it's safer to put the kernel on a different partition.

Boot the system

As you power up the Pandora, hold the shoulder button R. A menu should appear, allowing you to boot from the SD card. (this step isn't necessary if you chose to create an autoboot.txt instead of boot.txt). Remember that this will be an un-configured image, taking a little while longer to boot, and giving the first-run dialogue.

Access the NAND

Once you're booted into the system from SD, you may want access to the NAND rootfs. The following will let you do that.

sudo mkdir /mnt/nand
sudo ubiattach /dev/ubi_ctrl -m 4
sudo mount -t ubifs ubi0:rootfs /mnt/nand

Other information

An alternative approach to using an SD card to increase the space accessible to the system is OS Extend. This allows the root filesystem to exist on more than one physical device.

References

• Skeezix's blog
• GP32x Forum Topic, "Up to date firmware tarball"
• Official firmware page
• The GUI-driven SD installer by David Boucher