Fix initramfs loading bug introduced in f407b0626f0160fa8cca67c548c8de38c8353e16
[qi.git] / README
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