| 1 | Qi |
| 2 | == |
| 3 | |
| 4 | Qi (named by Alan Cox on Openmoko kernel list) is a minimal bootloader that |
| 5 | "breathes life" into Linux. Its goal is to stay close to the minimum needed |
| 6 | to "load" and then "boot" Linux -- no boot menus, additional peripheral init |
| 7 | or private states. |
| 8 | |
| 9 | |
| 10 | What's wrong with U-Boot, they keep telling people to not reinvent the wheel? |
| 11 | ============================================================================= |
| 12 | |
| 13 | U-Boot is gradually becoming a simplified knockoff of Linux. After using it a |
| 14 | while, it became clear we were cutting and pasting drivers into U-Boot from |
| 15 | Linux, cutting them down and not having a plan to maintain the U-Boot versions |
| 16 | as the Linux ones were changed. |
| 17 | |
| 18 | We decided that we would use full Linux for things that Linux is good at and |
| 19 | only have the bootloader do the device init that is absolutely required before |
| 20 | Linux can be pulled into memory and started. In practice since we had a working |
| 21 | U-Boot implementation it meant cutting that right down to the bone (start.S |
| 22 | mainly for s3c2442) and then building it up from scratch optimized to just do |
| 23 | load and boot. |
| 24 | |
| 25 | |
| 26 | Samsung - specific boot sequence |
| 27 | ================================ |
| 28 | |
| 29 | Right now Qi supports Samsung "steppingstone" scheme devices, but in fact it's |
| 30 | the same in processors like iMX31 that there is a small area of SRAM that is |
| 31 | prepped with NAND content via ROM on the device. There's nothing that stops Qi |
| 32 | use on processors without steppingstone, although the ATAG stuff assumes we deal |
| 33 | with ARM based processor. |
| 34 | |
| 35 | |
| 36 | Per-CPU Qi |
| 37 | ========== |
| 38 | |
| 39 | Qi has a concept of a single bootloader binary created per CPU type. The |
| 40 | different devices that use that CPU are all supported in the same binary. At |
| 41 | runtime after the common init is done, Qi asks each supported device code in |
| 42 | turn if it recognizes the device as being handled by it, the first one to reply |
| 43 | that it knows the device gets to control the rest of the process. |
| 44 | |
| 45 | Consequently, there is NO build-time configuration file as found on U-Boot |
| 46 | except a make env var that sets the CPU type being built, eg: |
| 47 | |
| 48 | make CPU=s3c6410 |
| 49 | |
| 50 | |
| 51 | Booting Heuristics |
| 52 | ================== |
| 53 | |
| 54 | Qi has one or more ways to fetch a kernel depending on the device it finds it is |
| 55 | running on, for example on GTA02 it can use NAND and SD card devices. It goes |
| 56 | through these device-specific storage devices in order and tries to boot the |
| 57 | first viable kernel it finds, usually /boot/<uImage-device>.bin for example |
| 58 | /boot/uImage-GTA02.bin. |
| 59 | |
| 60 | The default order for GTA02 is: 1st SD primary partition, 2nd primary |
| 61 | partition, 3rd primary partition, NAND kernel partition. |
| 62 | |
| 63 | You can disable a rootfs for consideration for boot if you add a file |
| 64 | /boot/noboot-<device>, eg, /boot/noboot-GTA02. This differs from renaming or |
| 65 | deleting the kernel image because updating the kernel package would give you a |
| 66 | working kernel again and allow boot, whereas the noboot indication will remain |
| 67 | until you remove it. |
| 68 | |
| 69 | The kernel commandline used is associated with the storage device and partition, |
| 70 | this allows the correct root= line to be arrived at without any work. |
| 71 | |
| 72 | If no kernel image can be found, Qi falls back to doing a memory test. |
| 73 | |
| 74 | |
| 75 | Appending to commandline |
| 76 | ======================== |
| 77 | |
| 78 | You can append to the Qi commandline by creating a file /boot/append-<device>, |
| 79 | eg, /boot/append-GTA02 containing the additional kernel commandline you want. |
| 80 | |
| 81 | This means you can affect the boot per-rootfs, but that if you reimage the |
| 82 | rootfs you at the same time define what is appeneded. Because these files are |
| 83 | looked for with the <device> name in them, options can be selected depending on |
| 84 | the device the rootfs is run on. |
| 85 | |
| 86 | |
| 87 | Initrd support |
| 88 | ============== |
| 89 | |
| 90 | Initrd or initramfs in separate file is supported to be loaded at given |
| 91 | memory address in addition to kernel image. The ATAGs are issued accordingly. |
| 92 | |
| 93 | |
| 94 | Interactive UI |
| 95 | ============== |
| 96 | |
| 97 | Being minimalistic by its nature, Qi has very limited abilities to |
| 98 | interact with a user. On GTA02 the red LED and the vibrator are used |
| 99 | (if the battery is in good condition) to notify user of the following |
| 100 | actions: |
| 101 | |
| 102 | The LED is turned on either on: |
| 103 | - Successful partition mount |
| 104 | - Successful kernel pull |
| 105 | - Successful initramfs pull |
| 106 | |
| 107 | The LED is turned off and vibrator runs briefly either on: |
| 108 | - Fail of kernel pull |
| 109 | - Fail of initramfs pull |
| 110 | - Fail of mount partition |
| 111 | - Skipping of current boot possibility |
| 112 | |
| 113 | The LED is turned off either on: |
| 114 | - Start of the kernel |
| 115 | - Start of the mem test |
| 116 | - Start of the kernel pull |
| 117 | - Start of the initramfs pull |
| 118 | |
| 119 | If a user presses the AUX button after successful partition mount and |
| 120 | before start of the kernel pull (that is, while the red LED is on), |
| 121 | this boot possibility is skipped (and GTA02 owners can feel |
| 122 | vibration). If a user holds the POWER button just before start of the |
| 123 | kernel, debugging parameters are added to the kernel command line |
| 124 | and a lot of information is output to the screen. |
| 125 | |
| 126 | Functional Differences from U-Boot on GTA02 |
| 127 | =========================================== |
| 128 | |
| 129 | - Backlight and USB is not enabled until Linux starts after a few seconds |
| 130 | |
| 131 | - No startup splash screen |
| 132 | |
| 133 | - by default there is no boot spew on the LCM |
| 134 | |
| 135 | - On GTAxx boots from first uSD ext2 / 3 partition containing |
| 136 | /boot/uImage-<devicename>.bin present, eg, /boot/uImage-GTA02.bin, it checks |
| 137 | first three partitions in turn |
| 138 | |
| 139 | - On GTA01 and 02 if nothing is workable on the SD Card, or it is not present, |
| 140 | Qi will try to boot from NAND |
| 141 | |
| 142 | - You can disable a partition for boot by creating /boot/noboot-<devicename>, |
| 143 | eg, /boot/noboot-GTA02, it will skip it and check the next partition |
| 144 | |
| 145 | - Way faster |
| 146 | |
| 147 | - There is no concept of "staying in the bootloader". The bootloader exits to |
| 148 | Linux as fast as possible, that's all it does. |
| 149 | |
| 150 | |
