cosmetic: doc: uImage.FIT: fix typos
[platform/kernel/u-boot.git] / doc / uImage.FIT / command_syntax_extensions.txt
1 Command syntax extensions for the new uImage format
2 ===================================================
3
4 Author: Bartlomiej Sieka <tur@semihalf.com>
5
6 With the introduction of the new uImage format, bootm command (and other
7 commands as well) have to understand new syntax of the arguments. This is
8 necessary in order to specify objects contained in the new uImage, on which
9 bootm has to operate. This note attempts to first summarize bootm usage
10 scenarios, and then introduces new argument syntax.
11
12
13 bootm usage scenarios
14 ---------------------
15
16 Below is a summary of bootm usage scenarios, focused on booting a PowerPC
17 Linux kernel. The purpose of the following list is to document a complete list
18 of supported bootm usages.
19
20 Note: U-Boot supports two methods of booting a PowerPC Linux kernel: old way,
21 i.e., without passing the Flattened Device Tree (FDT), and new way, where the
22 kernel is passed a pointer to the FDT. The boot method is indicated for each
23 scenario.
24
25
26 1.  bootm               boot image at the current address, equivalent to 2,3,8
27
28 Old uImage:
29 2.  bootm <addr1>                   /* single image at <addr1> */
30 3.  bootm <addr1>                   /* multi-image at <addr1>  */
31 4.  bootm <addr1> -                 /* multi-image at <addr1>  */
32 5.  bootm <addr1> <addr2>           /* single image at <addr1> */
33 6.  bootm <addr1> <addr2> <addr3>   /* single image at <addr1> */
34 7.  bootm <addr1> -       <addr3>   /* single image at <addr1> */
35
36 New uImage:
37 8.  bootm <addr1>
38 9.  bootm [<addr1>]:<subimg1>
39 10. bootm [<addr1>]#<conf>
40 11. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2>
41 12. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> [<addr3>]:<subimg3>
42 13. bootm [<addr1>]:<subimg1> [<addr2>]:<subimg2> <addr3>
43 14. bootm [<addr1>]:<subimg1> -                   [<addr3>]:<subimg3>
44 15. bootm [<addr1>]:<subimg1> -                   <addr3>
45
46
47 Ad. 1. This is equivalent to cases 2,3,8, depending on the type of image at
48 the current image address.
49 - boot method: see cases 2,3,8
50
51 Ad. 2. Boot kernel image located at <addr1>.
52 - boot method: non-FDT
53
54 Ad. 3. First and second components of the image at <addr1> are assumed to be a
55 kernel and a ramdisk, respectively. The kernel is booted with initrd loaded
56 with the ramdisk from the image.
57 - boot method: depends on the number of components at <addr1>, and on whether
58   U-Boot is compiled with OF support:
59
60                     |          2 components |          3 components |
61                     |      (kernel, initrd) | (kernel, initrd, fdt) |
62 ---------------------------------------------------------------------
63 #ifdef CONFIG_OF_*  |               non-FDT |                   FDT |
64 #ifndef CONFIG_OF_* |               non-FDT |               non-FDT |
65
66 Ad. 4. Similar to case 3, but the kernel is booted without initrd.  Second
67 component of the multi-image is irrelevant (it can be a dummy, 1-byte file).
68 - boot method: see case 3
69
70 Ad. 5. Boot kernel image located at <addr1> with initrd loaded with ramdisk
71 from the image at <addr2>.
72 - boot method: non-FDT
73
74 Ad. 6. <addr1> is the address of a kernel image, <addr2> is the address of a
75 ramdisk image, and <addr3> is the address of a FDT binary blob.  Kernel is
76 booted with initrd loaded with ramdisk from the image at <addr2>.
77 - boot method: FDT
78
79 Ad. 7. <addr1> is the address of a kernel image and <addr3> is the address of
80 a FDT binary blob. Kernel is booted without initrd.
81 - boot method: FDT
82
83 Ad. 8. Image at <addr1> is assumed to contain a default configuration, which
84 is booted.
85 - boot method: FDT or non-FDT, depending on whether the default configuration
86   defines FDT
87
88 Ad. 9. Similar to case 2: boot kernel stored in <subimg1> from the image at
89 address <addr1>.
90 - boot method: non-FDT
91
92 Ad. 10. Boot configuration <conf> from the image at <addr1>.
93 - boot method: FDT or non-FDT, depending on whether the configuration given
94   defines FDT
95
96 Ad. 11. Equivalent to case 5: boot kernel stored in <subimg1> from the image
97 at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
98 <addr2>.
99 - boot method: non-FDT
100
101 Ad. 12. Equivalent to case 6: boot kernel stored in <subimg1> from the image
102 at <addr1> with initrd loaded with ramdisk <subimg2> from the image at
103 <addr2>, and pass FDT blob <subimg3> from the image at <addr3>.
104 - boot method: FDT
105
106 Ad. 13. Similar to case 12, the difference being that <addr3> is the address
107 of FDT binary blob that is to be passed to the kernel.
108 - boot method: FDT
109
110 Ad. 14. Equivalent to case 7: boot kernel stored in <subimg1> from the image
111 at <addr1>, without initrd, and pass FDT blob <subimg3> from the image at
112 <addr3>.
113 - boot method: FDT
114
115 Ad. 15. Similar to case 14, the difference being that <addr3> is the address
116 of the FDT binary blob that is to be passed to the kernel.
117 - boot method: FDT
118
119
120 New uImage argument syntax
121 --------------------------
122
123 New uImage support introduces two new forms for bootm arguments, with the
124 following syntax:
125
126 - new uImage sub-image specification
127 <addr>:<sub-image unit_name>
128
129 - new uImage configuration specification
130 <addr>#<configuration unit_name>
131
132
133 Examples:
134
135 - boot kernel "kernel@1" stored in a new uImage located at 200000:
136 bootm 200000:kernel@1
137
138 - boot configuration "cfg@1" from a new uImage located at 200000:
139 bootm 200000#cfg@1
140
141 - boot "kernel@1" from a new uImage at 200000 with initrd "ramdisk@2" found in
142   some other new uImage stored at address 800000:
143 bootm 200000:kernel@1 800000:ramdisk@2
144
145 - boot "kernel@2" from a new uImage at 200000, with initrd "ramdisk@1" and FDT
146   "fdt@1", both stored in some other new uImage located at 800000:
147 bootm 200000:kernel@1 800000:ramdisk@1 800000:fdt@1
148
149 - boot kernel "kernel@2" with initrd "ramdisk@2", both stored in a new uImage
150   at address 200000, with a raw FDT blob stored at address 600000:
151 bootm 200000:kernel@2 200000:ramdisk@2 600000
152
153 - boot kernel "kernel@2" from new uImage at 200000 with FDT "fdt@1" from the
154   same new uImage:
155 bootm 200000:kernel@2 - 200000:fdt@1
156
157
158 Note on current image address
159 -----------------------------
160
161 When bootm is called without arguments, the image at current image address is
162 booted. The current image address is the address set most recently by a load
163 command, etc, and is by default equal to CONFIG_SYS_LOAD_ADDR. For example, consider
164 the following commands:
165
166 tftp 200000 /tftpboot/kernel
167 bootm
168 Last command is equivalent to:
169 bootm 200000
170
171 In case of the new uImage argument syntax, the address portion of any argument
172 can be omitted. If <addr3> is omitted, then it is assumed that image at
173 <addr2> should be used. Similarly, when <addr2> is omitted, it is assumed that
174 image at <addr1> should be used. If <addr1> is omitted, it is assumed that the
175 current image address is to be used. For example, consider the following
176 commands:
177
178 tftp 200000 /tftpboot/uImage
179 bootm :kernel@1
180 Last command is equivalent to:
181 bootm 200000:kernel@1
182
183 tftp 200000 /tftpboot/uImage
184 bootm 400000:kernel@1 :ramdisk@1
185 Last command is equivalent to:
186 bootm 400000:kernel@1 400000:ramdisk@1
187
188 tftp 200000 /tftpboot/uImage
189 bootm :kernel@1 400000:ramdisk@1 :fdt@1
190 Last command is equivalent to:
191 bootm 200000:kernel@1 400000:ramdisk@1 400000:fdt@1