.TH "QI" "8"
.SH "NAME"
Qi \- lightweight bootloader for OpenMoko Freerunner
.SH "DESCRIPTION"
.PP
\fBQi\fP is a lightweight bootloader for OpenMoko Freerunner
phones. It can be installed to the beginning of the NAND flash to load
a kernel and an initramfs from either an SD card or NAND flash.

.SH "STORAGE ORGANIZATION"
.PP
Freerunner has three types of non-volatile storage: NOR flash, NAND
flash and an SD card. NOR flash is read-only and holds a copy of
the U-boot bootloader:

 $ sudo strings /dev/mtd0 | grep Bootloader
 U-Boot 1.3.2-moko12 (May  9 2008 - 10:28:48)

Code in NOR flash is executed only if AUX button is held when you hit
POWER button to boot the system. You can use U-boot to flash NAND
partitions using the DFU protocol. Qi does not support DFU.

.PP
NAND flash is divided into several partitions. This mapping is passed
as a commandline argument to Linux so you can view it simply by
reading /proc/mtd:

 $ cat /proc/mtd
 dev:    size   erasesize  name
 mtd0: 00200000 00010000 "physmap-flash.0"
 mtd1: 00040000 00020000 "qi"
 mtd2: 00040000 00020000 "depr-ub-env"
 mtd3: 00820000 00020000 "kernel"
 mtd4: 000a0000 00020000 "depr"
 mtd5: 00040000 00020000 "identity-ext2"
 mtd6: 0f680000 00020000 "rootfs"

You can check what bootloader exists in the begining of the NAND flash
by running e.g.:

 $ sudo strings /dev/mtd1 | grep Bootloader
 Qi Bootloader s3c2442  ginger debian_20100107-1

Qi support both uSD and uSDHC cards. It can parse a regular MSDOS
partition table and has a read-only ext2 filesystem driver which seems
to work also with ext3 (with or without journaling) and ext4 without
extents.

.SH "BOOT ORDER"
.PP
Qi tries to boot from five different locations. It moves to the next
entry in the list below if it fails to load a kernel or if you hit AUX
while Qi is reading the kernel or the initramfs:

\fBBoot option 1\fP

 Kernel: /boot/uImage-GTA02.bin from SD partition 1
 Initramfs: /boot/initrd-GTA02.bin from SD partition 1
 Extra arguments: /boot/append-GTA02.bin from SD partition 1

\fBBoot option 2\fP

 Kernel: /boot/uImage-GTA02.bin.2 from SD partition 1
 Initramfs: /boot/initrd-GTA02.bin.2 from SD partition 1
 Extra arguments: /boot/append-GTA02.bin.2 from SD partition 1

\fBBoot option 3\fP

 Kernel: /boot/uImage-GTA02.bin from SD partition 2
 Initramfs: /boot/initrd-GTA02.bin from SD partition 2
 Extra arguments: /boot/append-GTA02.bin from SD partition 2

\fBBoot option 4\fP

 Kernel: /boot/uImage-GTA02.bin from SD partition 3
 Initramfs: /boot/initrd-GTA02.bin from SD partition 3
 Extra arguments: /boot/append-GTA02.bin from SD partition 3

\fBBoot option 5\fP

 Kernel: kernel partition from NAND flash (/dev/mtd3)
 Initramfs: not supported
 Extra arguments: not supported

.PP
The kernel can be either in uImage or zImage format. Qi understands
symlinks.

.SH "SEE ALSO"
.PP
Additional documentation is available in the README file and OpenMoko
wiki.