Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 1 | How to use images in the new image format |
| 2 | ========================================= |
| 3 | |
| 4 | Author: Bartlomiej Sieka <tur@semihalf.com> |
| 5 | |
| 6 | |
| 7 | Overview |
| 8 | -------- |
| 9 | |
| 10 | The new uImage format allows more flexibility in handling images of various |
| 11 | types (kernel, ramdisk, etc.), it also enhances integrity protection of images |
| 12 | with sha1 and md5 checksums. |
| 13 | |
| 14 | Two auxiliary tools are needed on the development host system in order to |
| 15 | create an uImage in the new format: mkimage and dtc, although only one |
| 16 | (mkimage) is invoked directly. dtc is called from within mkimage and operates |
| 17 | behind the scenes, but needs to be present in the $PATH nevertheless. It is |
| 18 | important that the dtc used has support for binary includes -- refer to |
| 19 | www.jdl.com for its latest version. mkimage (together with dtc) takes as input |
| 20 | an image source file, which describes the contents of the image and defines |
| 21 | its various properties used during booting. By convention, image source file |
| 22 | has the ".its" extension, also, the details of its format are given in |
Masahiro Yamada | 35884fc | 2014-01-16 11:05:23 +0900 | [diff] [blame] | 23 | doc/uImage.FIT/source_file_format.txt. The actual data that is to be included in |
| 24 | the uImage (kernel, ramdisk, etc.) is specified in the image source file in the |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 25 | form of paths to appropriate data files. The outcome of the image creation |
| 26 | process is a binary file (by convention with the ".itb" extension) that |
| 27 | contains all the referenced data (kernel, ramdisk, etc.) and other information |
| 28 | needed by U-Boot to handle the uImage properly. The uImage file is then |
| 29 | transferred to the target (e.g., via tftp) and booted using the bootm command. |
| 30 | |
| 31 | To summarize the prerequisites needed for new uImage creation: |
| 32 | - mkimage |
| 33 | - dtc (with support for binary includes) |
| 34 | - image source file (*.its) |
| 35 | - image data file(s) |
| 36 | |
| 37 | |
| 38 | Here's a graphical overview of the image creation and booting process: |
| 39 | |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 40 | image source file mkimage + dtc transfer to target |
| 41 | + ---------------> image file --------------------> bootm |
Masahiro Yamada | 35884fc | 2014-01-16 11:05:23 +0900 | [diff] [blame] | 42 | image data file(s) |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 43 | |
| 44 | |
| 45 | Example 1 -- old-style (non-FDT) kernel booting |
| 46 | ----------------------------------------------- |
| 47 | |
| 48 | Consider a simple scenario, where a PPC Linux kernel built from sources on the |
| 49 | development host is to be booted old-style (non-FDT) by U-Boot on an embedded |
| 50 | target. Assume that the outcome of the build is vmlinux.bin.gz, a file which |
| 51 | contains a gzip-compressed PPC Linux kernel (the only data file in this case). |
Bartlomiej Sieka | 739d2d7 | 2008-03-20 23:10:19 +0100 | [diff] [blame] | 52 | The uImage can be produced using the image source file |
| 53 | doc/uImage.FIT/kernel.its (note that kernel.its assumes that vmlinux.bin.gz is |
| 54 | in the current working directory; if desired, an alternative path can be |
| 55 | specified in the kernel.its file). Here's how to create the image and inspect |
| 56 | its contents: |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 57 | |
| 58 | [on the host system] |
| 59 | $ mkimage -f kernel.its kernel.itb |
| 60 | DTC: dts->dtb on file "kernel.its" |
| 61 | $ |
| 62 | $ mkimage -l kernel.itb |
| 63 | FIT description: Simple image with single Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 64 | Created: Tue Mar 11 17:26:15 2008 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 65 | Image 0 (kernel@1) |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 66 | Description: Vanilla Linux kernel |
| 67 | Type: Kernel Image |
| 68 | Compression: gzip compressed |
| 69 | Data Size: 943347 Bytes = 921.24 kB = 0.90 MB |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 70 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 71 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 72 | Load Address: 0x00000000 |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 73 | Entry Point: 0x00000000 |
| 74 | Hash algo: crc32 |
| 75 | Hash value: 2ae2bb40 |
| 76 | Hash algo: sha1 |
| 77 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 78 | Default Configuration: 'config@1' |
| 79 | Configuration 0 (config@1) |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 80 | Description: Boot Linux kernel |
| 81 | Kernel: kernel@1 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 82 | |
| 83 | |
| 84 | The resulting image file kernel.itb can be now transferred to the target, |
| 85 | inspected and booted (note that first three U-Boot commands below are shown |
| 86 | for completeness -- they are part of the standard booting procedure and not |
| 87 | specific to the new image format). |
| 88 | |
| 89 | [on the target system] |
| 90 | => print nfsargs |
| 91 | nfsargs=setenv bootargs root=/dev/nfs rw nfsroot=${serverip}:${rootpath} |
| 92 | => print addip |
| 93 | addip=setenv bootargs ${bootargs} ip=${ipaddr}:${serverip}:${gatewayip}:${netmask}:${hostname}:${netdev}:off panic=1 |
| 94 | => run nfsargs addip |
| 95 | => tftp 900000 /path/to/tftp/location/kernel.itb |
Heiko Schocher | c5e8405 | 2010-07-20 17:45:02 +0200 | [diff] [blame] | 96 | Using FEC device |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 97 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
| 98 | Filename '/path/to/tftp/location/kernel.itb'. |
| 99 | Load address: 0x900000 |
| 100 | Loading: ################################################################# |
| 101 | done |
| 102 | Bytes transferred = 944464 (e6950 hex) |
| 103 | => iminfo |
| 104 | |
| 105 | ## Checking Image at 00900000 ... |
| 106 | FIT image found |
| 107 | FIT description: Simple image with single Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 108 | Created: 2008-03-11 16:26:15 UTC |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 109 | Image 0 (kernel@1) |
| 110 | Description: Vanilla Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 111 | Type: Kernel Image |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 112 | Compression: gzip compressed |
| 113 | Data Start: 0x009000e0 |
| 114 | Data Size: 943347 Bytes = 921.2 kB |
| 115 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 116 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 117 | Load Address: 0x00000000 |
| 118 | Entry Point: 0x00000000 |
| 119 | Hash algo: crc32 |
| 120 | Hash value: 2ae2bb40 |
| 121 | Hash algo: sha1 |
| 122 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 |
| 123 | Default Configuration: 'config@1' |
| 124 | Configuration 0 (config@1) |
| 125 | Description: Boot Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 126 | Kernel: kernel@1 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 127 | |
| 128 | => bootm |
| 129 | ## Booting kernel from FIT Image at 00900000 ... |
| 130 | Using 'config@1' configuration |
| 131 | Trying 'kernel@1' kernel subimage |
| 132 | Description: Vanilla Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 133 | Type: Kernel Image |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 134 | Compression: gzip compressed |
| 135 | Data Start: 0x009000e0 |
| 136 | Data Size: 943347 Bytes = 921.2 kB |
| 137 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 138 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 139 | Load Address: 0x00000000 |
| 140 | Entry Point: 0x00000000 |
| 141 | Hash algo: crc32 |
| 142 | Hash value: 2ae2bb40 |
| 143 | Hash algo: sha1 |
| 144 | Hash value: 3c200f34e2c226ddc789240cca0c59fc54a67cf4 |
| 145 | Verifying Hash Integrity ... crc32+ sha1+ OK |
| 146 | Uncompressing Kernel Image ... OK |
| 147 | Memory BAT mapping: BAT2=256Mb, BAT3=0Mb, residual: 0Mb |
| 148 | Linux version 2.4.25 (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.0 4.0.0)) #2 czw lip 5 17:56:18 CEST 2007 |
| 149 | On node 0 totalpages: 65536 |
| 150 | zone(0): 65536 pages. |
| 151 | zone(1): 0 pages. |
| 152 | zone(2): 0 pages. |
| 153 | Kernel command line: root=/dev/nfs rw nfsroot=192.168.1.1:/opt/eldk-4.1/ppc_6xx ip=192.168.160.5:192.168.1.1::255.255.0.0:lite5200b:eth0:off panic=1 |
| 154 | Calibrating delay loop... 307.20 BogoMIPS |
| 155 | |
| 156 | |
| 157 | Example 2 -- new-style (FDT) kernel booting |
| 158 | ------------------------------------------- |
| 159 | |
| 160 | Consider another simple scenario, where a PPC Linux kernel is to be booted |
| 161 | new-style, i.e., with a FDT blob. In this case there are two prerequisite data |
| 162 | files: vmlinux.bin.gz (Linux kernel) and target.dtb (FDT blob). The uImage can |
Bartlomiej Sieka | 739d2d7 | 2008-03-20 23:10:19 +0100 | [diff] [blame] | 163 | be produced using image source file doc/uImage.FIT/kernel_fdt.its like this |
| 164 | (note again, that both prerequisite data files are assumed to be present in |
| 165 | the current working directory -- image source file kernel_fdt.its can be |
| 166 | modified to take the files from some other location if needed): |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 167 | |
| 168 | [on the host system] |
| 169 | $ mkimage -f kernel_fdt.its kernel_fdt.itb |
| 170 | DTC: dts->dtb on file "kernel_fdt.its" |
| 171 | $ |
| 172 | $ mkimage -l kernel_fdt.itb |
| 173 | FIT description: Simple image with single Linux kernel and FDT blob |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 174 | Created: Tue Mar 11 16:29:22 2008 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 175 | Image 0 (kernel@1) |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 176 | Description: Vanilla Linux kernel |
| 177 | Type: Kernel Image |
| 178 | Compression: gzip compressed |
| 179 | Data Size: 1092037 Bytes = 1066.44 kB = 1.04 MB |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 180 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 181 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 182 | Load Address: 0x00000000 |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 183 | Entry Point: 0x00000000 |
| 184 | Hash algo: crc32 |
| 185 | Hash value: 2c0cc807 |
| 186 | Hash algo: sha1 |
| 187 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 188 | Image 1 (fdt@1) |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 189 | Description: Flattened Device Tree blob |
| 190 | Type: Flat Device Tree |
| 191 | Compression: uncompressed |
| 192 | Data Size: 16384 Bytes = 16.00 kB = 0.02 MB |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 193 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 194 | Hash algo: crc32 |
| 195 | Hash value: 0d655d71 |
| 196 | Hash algo: sha1 |
| 197 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 198 | Default Configuration: 'conf@1' |
| 199 | Configuration 0 (conf@1) |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 200 | Description: Boot Linux kernel with FDT blob |
| 201 | Kernel: kernel@1 |
| 202 | FDT: fdt@1 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 203 | |
| 204 | |
| 205 | The resulting image file kernel_fdt.itb can be now transferred to the target, |
| 206 | inspected and booted: |
| 207 | |
| 208 | [on the target system] |
| 209 | => tftp 900000 /path/to/tftp/location/kernel_fdt.itb |
Heiko Schocher | c5e8405 | 2010-07-20 17:45:02 +0200 | [diff] [blame] | 210 | Using FEC device |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 211 | TFTP from server 192.168.1.1; our IP address is 192.168.160.5 |
| 212 | Filename '/path/to/tftp/location/kernel_fdt.itb'. |
| 213 | Load address: 0x900000 |
| 214 | Loading: ################################################################# |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 215 | ########### |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 216 | done |
| 217 | Bytes transferred = 1109776 (10ef10 hex) |
| 218 | => iminfo |
| 219 | |
| 220 | ## Checking Image at 00900000 ... |
| 221 | FIT image found |
| 222 | FIT description: Simple image with single Linux kernel and FDT blob |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 223 | Created: 2008-03-11 15:29:22 UTC |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 224 | Image 0 (kernel@1) |
| 225 | Description: Vanilla Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 226 | Type: Kernel Image |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 227 | Compression: gzip compressed |
| 228 | Data Start: 0x009000ec |
| 229 | Data Size: 1092037 Bytes = 1 MB |
| 230 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 231 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 232 | Load Address: 0x00000000 |
| 233 | Entry Point: 0x00000000 |
| 234 | Hash algo: crc32 |
| 235 | Hash value: 2c0cc807 |
| 236 | Hash algo: sha1 |
| 237 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb |
| 238 | Image 1 (fdt@1) |
| 239 | Description: Flattened Device Tree blob |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 240 | Type: Flat Device Tree |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 241 | Compression: uncompressed |
| 242 | Data Start: 0x00a0abdc |
| 243 | Data Size: 16384 Bytes = 16 kB |
| 244 | Architecture: PowerPC |
| 245 | Hash algo: crc32 |
| 246 | Hash value: 0d655d71 |
| 247 | Hash algo: sha1 |
| 248 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def |
| 249 | Default Configuration: 'conf@1' |
| 250 | Configuration 0 (conf@1) |
| 251 | Description: Boot Linux kernel with FDT blob |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 252 | Kernel: kernel@1 |
| 253 | FDT: fdt@1 |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 254 | => bootm |
| 255 | ## Booting kernel from FIT Image at 00900000 ... |
| 256 | Using 'conf@1' configuration |
| 257 | Trying 'kernel@1' kernel subimage |
| 258 | Description: Vanilla Linux kernel |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 259 | Type: Kernel Image |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 260 | Compression: gzip compressed |
| 261 | Data Start: 0x009000ec |
| 262 | Data Size: 1092037 Bytes = 1 MB |
| 263 | Architecture: PowerPC |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 264 | OS: Linux |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 265 | Load Address: 0x00000000 |
| 266 | Entry Point: 0x00000000 |
| 267 | Hash algo: crc32 |
| 268 | Hash value: 2c0cc807 |
| 269 | Hash algo: sha1 |
| 270 | Hash value: 264b59935470e42c418744f83935d44cdf59a3bb |
| 271 | Verifying Hash Integrity ... crc32+ sha1+ OK |
| 272 | Uncompressing Kernel Image ... OK |
| 273 | ## Flattened Device Tree from FIT Image at 00900000 |
| 274 | Using 'conf@1' configuration |
| 275 | Trying 'fdt@1' FDT blob subimage |
| 276 | Description: Flattened Device Tree blob |
Wolfgang Denk | 8f702ad | 2008-03-26 11:48:46 +0100 | [diff] [blame] | 277 | Type: Flat Device Tree |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 278 | Compression: uncompressed |
| 279 | Data Start: 0x00a0abdc |
| 280 | Data Size: 16384 Bytes = 16 kB |
| 281 | Architecture: PowerPC |
| 282 | Hash algo: crc32 |
| 283 | Hash value: 0d655d71 |
| 284 | Hash algo: sha1 |
| 285 | Hash value: 25ab4e15cd4b8a5144610394560d9c318ce52def |
| 286 | Verifying Hash Integrity ... crc32+ sha1+ OK |
| 287 | Booting using the fdt blob at 0xa0abdc |
| 288 | Loading Device Tree to 007fc000, end 007fffff ... OK |
| 289 | [ 0.000000] Using lite5200 machine description |
| 290 | [ 0.000000] Linux version 2.6.24-rc6-gaebecdfc (m8@hekate) (gcc version 4.0.0 (DENX ELDK 4.1 4.0.0)) #1 Sat Jan 12 15:38:48 CET 2008 |
| 291 | |
| 292 | |
| 293 | Example 3 -- advanced booting |
| 294 | ----------------------------- |
| 295 | |
Bartlomiej Sieka | 739d2d7 | 2008-03-20 23:10:19 +0100 | [diff] [blame] | 296 | Refer to doc/uImage.FIT/multi.its for an image source file that allows more |
Marian Balakowicz | 18710b8 | 2008-03-12 12:13:13 +0100 | [diff] [blame] | 297 | sophisticated booting scenarios (multiple kernels, ramdisks and fdt blobs). |