1MKIMAGE(1) General Commands Manual MKIMAGE(1)
2
6 mkimage - generate images for U-Boot
7
9 mkimage [-T type] -l image-file-name
10 mkimage [option ...] [-T type] image-file-name
12 mkimage [option ...] -f image-tree-source-file|auto image-file-name
14 mkimage [option ...] -F image-file-name
16
18 The mkimage command is used to create images for use with the U-Boot
19 boot loader. These images can contain the Linux kernel, device tree
20 blob, root file system image, firmware images etc., either separate or
21 combined.
22 mkimage supports many image formats. Some of these formats may be used
24 by embedded boot firmware to load U-Boot. Others may be used by U-Boot
25 to load Linux (or some other kernel):
26 The legacy image format concatenates the individual parts (for example,
28 kernel image, device tree blob and ramdisk image) and adds a 64 byte
29 header containing information about the target architecture, operating
30 system, image type, compression method, entry points, time stamp,
31 checksums, etc.
32 The new FIT (Flattened Image Tree) format allows for more flexibility
34 in handling images of various types and also enhances integrity protec‐
35 tion of images with stronger checksums. It also supports verified boot.
36
38 General options
39 -h
40 --help Print a help message and exit.
41 -l
43 --list mkimage lists the information contained in the header of an ex‐
44 isting U-Boot image.
45 -s
47 --no-copy
48 Don't copy in the image data. Depending on the image type, this
49 may create just the header, everything but the image data, or
50 nothing at all.
51 -T image-type
53 --type image-type
54 Parse image file as image-type. Pass list as image-type to see
55 the list of supported image types. If this option is absent,
56 then it defaults to kernel (legacy image). If this option is ab‐
57 sent when -l is passed, then mkimage will attempt to automati‐
58 cally detect the image type. Not all image types support auto‐
59 matic detection, so it may be necessary to pass -T explicitly.
60 When creating a FIT image with -f, the image type is always set
62 to flat_dt. In this case, -T specifies the image node's ‘type’
63 property. If -T is absent, then the ‘type’ property will default
64 to kernel.
65 -q
67 --quiet
68 Quiet. Don't print the image header.
69 -v
71 --verbose
72 Verbose. Print file names as they are added to the image.
73 -V
75 --version
76 Print version information and exit.
77 General image-creation options
79 -A architecture
80 --architecture architecture
81 Set the architecture. Pass -h as the architecture to see the
82 list of supported architectures. If -A is absent, it defaults to
83 ppc.
84 -O os
86 --os os
87 Set the operating system. The U-Boot bootm command changes boot
88 method based on the OS type. Pass -h as the os to see the list
89 of supported OSs. If -O is absent, it defaults to linux.
90 -C compression-type
92 --compression compression-type
93 Set the compression type. The image data should have already
94 been compressed using this compression type. mkimage will not
95 automatically compress image data. Pass -h as the compression-
96 type to see the list of supported compression types. If -C is
97 absent, it defaults to gzip.
98 -a load-address
100 --load-address load-address
101 Set the absolute address to load the image data to. load-ad‐
102 dress will be interpreted as a hexadecimal number.
103 -e entry-point
105 --entry-point entry-point
106 Set the absolute address of the image entry point. The U-Boot
107 bootm command will jump to this address after loading the image.
108 entry-point will be interpreted as a hexadecimal number.
109 -n primary-configuration
111 --config primary-configuration
112 Images may require additional configuration not specified with
113 other options, often in a image-type-specific format. The image
114 types which support this option and the format of their configu‐
115 ration are listed in CONFIGURATION.
116 -R secondary-configuration
118 --secondary-config secondary-configuration
119 Some image types support a second set of configuration data. The
120 image types which support secondary configuration and the formap
121 of their configuration are listed in CONFIGURATION.
122 -d image-data-file
124 --image image-data-file
125 Use image data from image-data-file. If the image-type is
126 multi, then multiple images may be specified, separated by
127 colons:
128 image-data-file[:image-data-file...]
130 -x
132 --xip Set the XIP (execute in place) flag. The U-Boot bootm command
133 will not load the image data, and instead will assume it is al‐
134 ready accessible at the load address (such as via memory-mapped
135 flash).
136 Options for creating FIT images
138 -b device-tree-file
139 --device-tree device-tree-file
140 Appends the device tree binary file (.dtb) to the FIT.
141 -c comment
143 --comment comment
144 Specifies a comment to be added when signing. This is typically
145 a message which describes how the image was signed or some other
146 useful information.
147 -D dtc-options
149 --dtcopts dtc-options
150 Provide additional options to the device tree compiler when cre‐
151 ating the image. See dtc(1) for documentation of possible op‐
152 tions. If -D is absent, it defaults to -I dts -O dtb -p 500.
153 -E
155 --external
156 After processing, move the image data outside the FIT and store
157 a data offset in the FIT. Images will be placed one after the
158 other immediately after the FIT, with each one aligned to a
159 4-byte boundary. The existing ‘data’ property in each image will
160 be replaced with ‘data-offset’ and ‘data-size’ properties. A
161 ‘data-offset’ of 0 indicates that it starts in the first
162 (4-byte-aligned) byte after the FIT.
163 -B alignment
165 --alignment alignment
166 The alignment, in hexadecimal, that external data will be
167 aligned to. This option only has an effect when -E is specified.
168 -p external-position
170 --position external-position
171 Place external data at a static external position. Instead of
172 writing a ‘data-offset’ property defining the offset from the
173 end of the FIT, -p will use ‘data-position’ as the absolute po‐
174 sition from the base of the FIT. See -E for details on using ex‐
175 ternal data.
176 -f image-tree-source-file | auto
178 --fit image-tree-source-file | auto
179 Image tree source file that describes the structure and contents
180 of the FIT image.
181 In some simple cases, the image tree source can be generated au‐
183 tomatically. To use this feature, pass -f auto. The -d, -A, -O,
184 -T, -C, -a, and -e options may be used to specify the image to
185 include in the FIT and its attributes. No image-tree-source-file
186 is required.
187 -F
189 --update
190 Indicates that an existing FIT image should be modified. No dtc
191 compilation will be performed and -f should not be passed. This
192 can be used to sign images with additional keys after initial
193 image creation.
194 -i ramdisk-file
196 --initramfs ramdisk-file
197 Append a ramdisk or initramfs file to the image.
198 -k key-directory
200 --key-dir key-directory
201 Specifies the directory containing keys to use for signing. This
202 directory should contain a private key file name.key for use
203 with signing, and a certificate name.crt (containing the public
204 key) for use with verification. The public key is only necessary
205 when embedding it into another device tree using -K. name de‐
206 faults to the value of the signature node's ‘key-name-hint’
207 property, but may be overridden using -g.
208 -G key-file
210 --key-file key-file
211 Specifies the private key file to use when signing. This option
212 may be used instead of -k.
213 -K key-destination
215 --key-dest key-destination
216 Specifies a compiled device tree binary file (typically .dtb) to
217 write public key information into. When a private key is used to
218 sign an image, the corresponding public key is written into this
219 file for for run-time verification. Typically the file here is
220 the device tree binary used by CONFIG_OF_CONTROL in U-Boot.
221 -g key-name-hint
223 --key-name-hint key-name-hint
224 Overrides the signature node's ‘key-name-hint’ property. This is
225 especially useful when signing an image with -f auto. This is
226 the name part of the key. The directory part is set by -k. This
227 option also indicates that the images included in the FIT should
228 be signed. If this option is specified, then -o must be speci‐
229 fied as well.
230 -o crypto,checksum
232 --algo crypto,checksum
233 Specifies the algorithm to be used for signing a FIT image. The
234 default is taken from the signature node's ‘algo’ property. The
235 valid values for crypto are:
236 rsa2048
238 rsa3072
239 rsa4096
240 ecdsa256
241 The valid values for checksum are
243 sha1
245 sha256
246 sha384
247 sha512
248 -r
250 --key-required
251 Specifies that keys used to sign the FIT are required. This
252 means that they must be verified for the image to boot. Without
253 this option, the verification will be optional (useful for test‐
254 ing but not for release).
255 -N engine
257 --engine engine
258 The openssl engine to use when signing and verifying the image.
259 For a complete list of available engines, refer to engine(1).
260 -t
262 --touch
263 Update the timestamp in the FIT.
264 Normally the FIT timestamp is created the first time mkimage
266 runs, when converting the source .its to the binary .fit file.
267 This corresponds to using -f. But if the original input to
268 mkimage is a binary file (already compiled), then the timestamp
269 is assumed to have been set previously.
270
272 This section documents the formats of the primary and secondary config‐
273 uration options for each image type which supports them.
274 aisimage
276 The primary configuration is a file containing a series of AIS (Appli‐
277 cation Image Script) commands, one per line. Each command has the form
278 command argument ...
280 See TI application report SPRAAG0E ⟨https://www.ti.com/lit/pdf/spraag0⟩
282 for details.
283 atmelimage
285 The primary configuration is a comma-separated list of NAND Flash pa‐
286 rameters of the form
287 parameter=value[,parameter=value...]
289 Valid parameters are
291 usePmecc
293 nbSectorPerPage
294 spareSize
295 eccBitReq
296 sectorSize
297 eccOffset
298 and valid values are decimal numbers. See section 11.4.4.1 of the
300 SAMA5D3 Series Data Sheet for valid values for each parameter.
301 imximage
303 The primary configuration is a file containing configuration commands,
304 as documented in doc/imx/mkimage/imximage.txt of the U-Boot source.
305 imx8image and imx8mimage
307 The primary configuration is a file containing configuration commands,
308 as documented in doc/imx/mkimage/imx8image.txt of the U-Boot source.
309 kwbimage
311 The primary configuration is a file containing configuration commands,
312 as documented in doc/imx/mkimage/kwbimage.txt of the U-Boot source.
313 mtk_image
315 The primary configuration is a semicolon-separated list of header op‐
316 tions of the form
317 key=value[;key=value...]
319 where the valid keys are:
321 Key Description
323 ───────────────────────────────────────────────────────────────────────────
324 lk If 1, then an LK (legacy) image header is used. Otherwise, a
325 BootROM image header is used.
326 lkname The name of the LK image header. The maximum length is 32
327 ASCII characters. If not specified, the default value is U-
328 Boot.
329 media The boot device. See below for valid values.
330 nandinfo The desired NAND device type. See below for valid values.
331 arm64 If 1, then this denotes an AArch64 image.
332 hdroffset Increase the reported size of the BRLYT header by this amount.
333 Valid values for media are:
335 Value Description
337 ─────────────────────────────────────────
338 nand Parallel NAND flash
339 snand Serial NAND flash
340 nor Serial NOR flash
341 emmc eMMC (Embedded Multi-Media Card)
342 sdmmc SD (Secure Digital) card
343 Valid values for nandinfo are:
345 Value NAND type Page size OOB size Total size
347 ──────────────────────────────────────────────────────────
348 2k+64 Serial 2KiB 64B
349 2k+120 Serial 2KiB 120B
350 2k+128 Serial 2KiB 128B
351 4k+256 Serial 4KiB 256B
352 1g:2k+64 Parallel 2KiB 64B 1Gbit
353 2g:2k+64 Parallel 2KiB 64B 2Gbit
354 4g:2k+64 Parallel 2KiB 64B 4Gbit
355 2g:2k+128 Parallel 2KiB 128B 2Gbit
356 4g:2k+128 Parallel 2KiB 128B 4Gbit
357 mxsimage
359 The primary configuration is a file containing configuration commands,
360 as documented in doc/imx/mkimage/mxsimage.txt of the U-Boot source.
361 omapimage
363 The primary configuration is the optional value byteswap. If present,
364 each 32-bit word of the image will have its bytes swapped (converting
365 from little-endian to big-endian, or vice versa).
366 pblimage
368 The primary configuration is a file containing the PBI (Pre-Boot Image)
369 header. Each line of the configuration has the format
370 value[ value...]
372 Where value is a 32-bit hexadecimal integer. Each value will, after be‐
374 ing converted to raw bytes, be literally prepended to the PBI.
375 The secondary configuration is a file with the same format as the pri‐
377 mary configuration file. It will be inserted into the image after the
378 primary configuration data and before the image data.
379 It is traditional to use the primary configuration file for the RCW
381 (Reset Configuration Word), and the secondary configuration file for
382 any additional PBI commands. However, it is also possible to convert an
383 existing PBI to the above format and “chain” additional data onto the
384 end of the image. This may be especially useful for creating secure
385 boot images.
386 rkimage
388 The primary configuration is the name of the processor to generate the
389 image for. Valid values are:
390 px30
392 rk3036
393 rk3066
394 rk3128
395 rk3188
396 rk322x
397 rk3288
398 rk3308
399 rk3328
400 rk3368
401 rk3399
402 rv1108
403 rk3568
404 sunxi_egon
406 The primary configuration is the name to use for the device tree.
407 ublimage
409 The primary configuration is a file containing configuration commands,
410 as documented in doc/README.ublimage of the U-Boot source.
411 zynqimage and zynqmpimage
413 For zynqmpimage, the primary configuration is a file containing the
414 PMUFW (Power Management Unit Firmware). zynqimage does not use the
415 primary configuration.
416 For both image types, the secondary configuration is a file containinig
418 initialization parameters, one per line. Each parameter has the form
419 address data
421 where address and data are hexadecimal integers. The boot ROM will
423 write each data to address when loading the image. At most 256 parame‐
424 ters may be specified in this manner.
425
427 Please report bugs to the U-Boot bug tracker ⟨https://source.denx.de/u-
428 boot/u-boot/issues⟩.
429
431 List image information:
432 mkimage -l uImage
434 Create legacy image with compressed PowerPC Linux kernel:
436 mkimage -A powerpc -O linux -T kernel -C gzip \
438 -a 0 -e 0 -n Linux -d vmlinux.gz uImage
439 Create FIT image with compressed PowerPC Linux kernel:
441 mkimage -f kernel.its kernel.itb
443 Create FIT image with compressed kernel and sign it with keys in the
445 /public/signing-keys directory. Add corresponding public keys into
446 u-boot.dtb, skipping those for which keys cannot be found. Also add a
447 comment.
448 mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \
450 -c "Kernel 3.8 image for production devices" kernel.itb
451 Add public keys to u-boot.dtb without needing a FIT to sign. This will
453 also create a FIT containing an images node with no data named un‐
454 used.itb.
455 mkimage -f auto -d /dev/null -k /public/signing-keys -g dev \
457 -o sha256,rsa2048 -K u-boot.dtb unused.itb
458 Update an existing FIT image, signing it with additional keys. Add
460 corresponding public keys into u-boot.dtb. This will resign all images
461 with keys that are available in the new directory. Images that request
462 signing with unavailable keys are skipped.
463 mkimage -F -k /secret/signing-keys -K u-boot.dtb \
465 -c "Kernel 3.8 image for production devices" kernel.itb
466 Create a FIT image containing a kernel, using automatic mode. No .its
468 file is required.
469 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
471 -c "Kernel 4.4 image for production devices" -d vmlinuz kernel.itb
472 Create a FIT image containing a kernel and some device tree files, us‐
474 ing automatic mode. No .its file is required.
475 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
477 -c "Kernel 4.4 image for production devices" -d vmlinuz \
478 -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb
479 Create a FIT image containing a signed kernel, using automatic mode. No
481 .its file is required.
482 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
484 -d vmlinuz -k /secret/signing-keys -g dev -o sha256,rsa2048 kernel.itb
485
487 dtc(1), dumpimage(1), openssl(1), the U-Boot documentation ⟨https://u-
488 boot.readthedocs.io/en/latest/index.html⟩
489U-Boot 2022-06-11 MKIMAGE(1)