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|auto-conf image-
14 file-name
15 mkimage [option ...] -F image-file-name
17
19 The mkimage command is used to create images for use with the U-Boot
20 boot loader. These images can contain the Linux kernel, device tree
21 blob, root file system image, firmware images etc., either separate or
22 combined.
23 mkimage supports many image formats. Some of these formats may be used
25 by embedded boot firmware to load U-Boot. Others may be used by U-Boot
26 to load Linux (or some other kernel):
27 The legacy image format concatenates the individual parts (for example,
29 kernel image, device tree blob and ramdisk image) and adds a 64 byte
30 header containing information about the target architecture, operating
31 system, image type, compression method, entry points, time stamp,
32 checksums, etc.
33 The new FIT (Flattened Image Tree) format allows for more flexibility
35 in handling images of various types and also enhances integrity protec‐
36 tion of images with stronger checksums. It also supports verified boot.
37
39 General options
40 -h
41 --help Print a help message and exit.
42 -l
44 --list mkimage lists the information contained in the header of an ex‐
45 isting U-Boot image.
46 -s
48 --no-copy
49 Don't copy in the image data. Depending on the image type, this
50 may create just the header, everything but the image data, or
51 nothing at all.
52 -T image-type
54 --type image-type
55 Parse image file as image-type. Pass list as image-type to see
56 the list of supported image types. If this option is absent,
57 then it defaults to kernel (legacy image). If this option is ab‐
58 sent when -l is passed, then mkimage will attempt to automati‐
59 cally detect the image type. Not all image types support auto‐
60 matic detection, so it may be necessary to pass -T explicitly.
61 When creating a FIT image with -f, the image type is always set
63 to flat_dt. In this case, -T specifies the image node's ‘type’
64 property. If -T is absent, then the ‘type’ property will default
65 to kernel.
66 -q
68 --quiet
69 Quiet. Don't print the image header.
70 -v
72 --verbose
73 Verbose. Print file names as they are added to the image.
74 -V
76 --version
77 Print version information and exit.
78 General image-creation options
80 -A architecture
81 --architecture architecture
82 Set the architecture. Pass -h as the architecture to see the
83 list of supported architectures. If -A is absent, it defaults to
84 ppc.
85 -O os
87 --os os
88 Set the operating system. The U-Boot bootm command changes boot
89 method based on the OS type. Pass -h as the os to see the list
90 of supported OSs. If -O is absent, it defaults to linux.
91 -C compression-type
93 --compression compression-type
94 Set the compression type. The image data should have already
95 been compressed using this compression type. mkimage will not
96 automatically compress image data. Pass -h as the compression-
97 type to see the list of supported compression types. If -C is
98 absent, it defaults to gzip.
99 -a load-address
101 --load-address load-address
102 Set the absolute address to load the image data to. load-ad‐
103 dress will be interpreted as a hexadecimal number.
104 -e entry-point
106 --entry-point entry-point
107 Set the absolute address of the image entry point. The U-Boot
108 bootm command will jump to this address after loading the image.
109 entry-point will be interpreted as a hexadecimal number.
110 -n primary-configuration
112 --config primary-configuration
113 Images may require additional configuration not specified with
114 other options, often in a image-type-specific format. The image
115 types which support this option and the format of their configu‐
116 ration are listed in CONFIGURATION.
117 -R secondary-configuration
119 --secondary-config secondary-configuration
120 Some image types support a second set of configuration data. The
121 image types which support secondary configuration and the formap
122 of their configuration are listed in CONFIGURATION.
123 -d image-data-file
125 --image image-data-file
126 Use image data from image-data-file. If the image-type is
127 multi, then multiple images may be specified, separated by
128 colons:
129 image-data-file[:image-data-file...]
131 -x
133 --xip Set the XIP (execute in place) flag. The U-Boot bootm command
134 will not load the image data, and instead will assume it is al‐
135 ready accessible at the load address (such as via memory-mapped
136 flash).
137 Options for creating FIT images
139 -b device-tree-file
140 --device-tree device-tree-file
141 Appends the device tree binary file (.dtb) to the FIT.
142 -c comment
144 --comment comment
145 Specifies a comment to be added when signing. This is typically
146 a message which describes how the image was signed or some other
147 useful information.
148 -D dtc-options
150 --dtcopts dtc-options
151 Provide additional options to the device tree compiler when cre‐
152 ating the image. See dtc(1) for documentation of possible op‐
153 tions. If -D is absent, it defaults to -I dts -O dtb -p 500.
154 -E
156 --external
157 After processing, move the image data outside the FIT and store
158 a data offset in the FIT. Images will be placed one after the
159 other immediately after the FIT, with each one aligned to a
160 4-byte boundary. The existing ‘data’ property in each image will
161 be replaced with ‘data-offset’ and ‘data-size’ properties. A
162 ‘data-offset’ of 0 indicates that it starts in the first
163 (4-byte-aligned) byte after the FIT.
164 -B alignment
166 --alignment alignment
167 The alignment, in hexadecimal, that external data will be
168 aligned to. This option only has an effect when -E is specified.
169 -p external-position
171 --position external-position
172 Place external data at a static external position. Instead of
173 writing a ‘data-offset’ property defining the offset from the
174 end of the FIT, -p will use ‘data-position’ as the absolute po‐
175 sition from the base of the FIT. See -E for details on using ex‐
176 ternal data.
177 -f image-tree-source-file | auto | auto-conf
179 --fit image-tree-source-file | auto | auto-conf
180 Image tree source file that describes the structure and contents
181 of the FIT image.
182 In some simple cases, the image tree source can be generated au‐
184 tomatically. To use this feature, pass -f auto. The -d, -A, -O,
185 -T, -C, -a, and -e options may be used to specify the image to
186 include in the FIT and its attributes. No image-tree-source-file
187 is required. The -g, -o, and -k or -G options may be used to get
188 ‘images’ signed subnodes in the generated auto FIT. Instead, to
189 get ‘configurations’ signed subnodes and ‘images’ hashed sub‐
190 nodes, pass -f auto-conf. In this case -g, -o, and -k or -G are
191 mandatory options.
192 -F
194 --update
195 Indicates that an existing FIT image should be modified. No dtc
196 compilation will be performed and -f should not be passed. This
197 can be used to sign images with additional keys after initial
198 image creation.
199 -i ramdisk-file
201 --initramfs ramdisk-file
202 Append a ramdisk or initramfs file to the image.
203 -k key-directory
205 --key-dir key-directory
206 Specifies the directory containing keys to use for signing. This
207 directory should contain a private key file name.key for use
208 with signing, and a certificate name.crt (containing the public
209 key) for use with verification. The public key is only necessary
210 when embedding it into another device tree using -K. name is
211 the value of the signature node's ‘key-name-hint’ property.
212 -G key-file
214 --key-file key-file
215 Specifies the private key file to use when signing. This option
216 may be used instead of -k. Useful when the private key file
217 basename does not match ‘key-name-hint’ value. But note that it
218 may lead to unexpected results when used together with -K and/or
219 -k options.
220 -K key-destination
222 --key-dest key-destination
223 Specifies a compiled device tree binary file (typically .dtb) to
224 write public key information into. When a private key is used to
225 sign an image, the corresponding public key is written into this
226 file for for run-time verification. Typically the file here is
227 the device tree binary used by CONFIG_OF_CONTROL in U-Boot.
228 -g key-name-hint
230 --key-name-hint key-name-hint
231 Specifies the value of signature node ‘key-name-hint’ property
232 for an automatically generated FIT image. It makes sense only
233 when used with -f auto or -f auto-conf. This option also indi‐
234 cates that the images or configurations included in the FIT
235 should be signed. If this option is specified, then -o must be
236 specified as well.
237 -o checksum,crypto
239 --algo checksum,crypto
240 Specifies the algorithm to be used for signing a FIT image,
241 overriding value taken from the signature node ‘algo’ property
242 in the image-tree-source-file. It is mandatory for automati‐
243 cally generated FIT.
244 The valid values for checksum are:
246 sha1
248 sha256
249 sha384
250 sha512
251 The valid values for crypto are:
253 rsa2048
255 rsa3072
256 rsa4096
257 ecdsa256
258 -r
260 --key-required
261 Specifies that keys used to sign the FIT are required. This
262 means that images or configurations signatures must be verified
263 before using them (i.e. to boot). Without this option, the veri‐
264 fication will be optional (useful for testing but not for re‐
265 lease). It makes sense only when used with -K. When both, im‐
266 ages and configurations, are signed, ‘required’ property value
267 will be "conf".
268 -N engine
270 --engine engine
271 The openssl engine to use when signing and verifying the image.
272 For a complete list of available engines, refer to engine(1).
273 -t
275 --touch
276 Update the timestamp in the FIT.
277 Normally the FIT timestamp is created the first time mkimage
279 runs, when converting the source .its to the binary .fit file.
280 This corresponds to using -f. But if the original input to
281 mkimage is a binary file (already compiled), then the timestamp
282 is assumed to have been set previously.
283
285 This section documents the formats of the primary and secondary config‐
286 uration options for each image type which supports them.
287 aisimage
289 The primary configuration is a file containing a series of AIS (Appli‐
290 cation Image Script) commands, one per line. Each command has the form
291 command argument ...
293 See TI application report SPRAAG0E ⟨https://www.ti.com/lit/pdf/spraag0⟩
295 for details.
296 atmelimage
298 The primary configuration is a comma-separated list of NAND Flash pa‐
299 rameters of the form
300 parameter=value[,parameter=value...]
302 Valid parameters are
304 usePmecc
306 nbSectorPerPage
307 spareSize
308 eccBitReq
309 sectorSize
310 eccOffset
311 and valid values are decimal numbers. See section 11.4.4.1 of the
313 SAMA5D3 Series Data Sheet for valid values for each parameter.
314 imximage
316 The primary configuration is a file containing configuration commands,
317 as documented in doc/imx/mkimage/imximage.txt of the U-Boot source.
318 imx8image and imx8mimage
320 The primary configuration is a file containing configuration commands,
321 as documented in doc/imx/mkimage/imx8image.txt of the U-Boot source.
322 kwbimage
324 The primary configuration is a file containing configuration commands,
325 as documented in doc/imx/mkimage/kwbimage.txt of the U-Boot source.
326 mtk_image
328 The primary configuration is a semicolon-separated list of header op‐
329 tions of the form
330 key=value[;key=value...]
332 where the valid keys are:
334 Key Description
336 ───────────────────────────────────────────────────────────────────────────
337 lk If 1, then an LK (legacy) image header is used. Otherwise, a
338 BootROM image header is used.
339 lkname The name of the LK image header. The maximum length is 32
343 ASCII characters. If not specified, the default value is U-
344 Boot.
345 media The boot device. See below for valid values.
346 nandinfo The desired NAND device type. See below for valid values.
347 arm64 If 1, then this denotes an AArch64 image.
348 hdroffset Increase the reported size of the BRLYT header by this amount.
349 Valid values for media are:
351 Value Description
353 ─────────────────────────────────────────
354 nand Parallel NAND flash
355 snand Serial NAND flash
356 nor Serial NOR flash
357 emmc eMMC (Embedded Multi-Media Card)
358 sdmmc SD (Secure Digital) card
359 Valid values for nandinfo are:
361 Value NAND type Page size OOB size Total size
363 ──────────────────────────────────────────────────────────
364 2k+64 Serial 2KiB 64B
365 2k+120 Serial 2KiB 120B
366 2k+128 Serial 2KiB 128B
367 4k+256 Serial 4KiB 256B
368 1g:2k+64 Parallel 2KiB 64B 1Gbit
369 2g:2k+64 Parallel 2KiB 64B 2Gbit
370 4g:2k+64 Parallel 2KiB 64B 4Gbit
371 2g:2k+128 Parallel 2KiB 128B 2Gbit
372 4g:2k+128 Parallel 2KiB 128B 4Gbit
373 mxsimage
375 The primary configuration is a file containing configuration commands,
376 as documented in doc/imx/mkimage/mxsimage.txt of the U-Boot source.
377 omapimage
379 The primary configuration is the optional value byteswap. If present,
380 each 32-bit word of the image will have its bytes swapped (converting
381 from little-endian to big-endian, or vice versa).
382 pblimage
384 The primary configuration is a file containing the PBI (Pre-Boot Image)
385 header. Each line of the configuration has the format
386 value[ value...]
388 Where value is a 32-bit hexadecimal integer. Each value will, after be‐
390 ing converted to raw bytes, be literally prepended to the PBI.
391 The secondary configuration is a file with the same format as the pri‐
393 mary configuration file. It will be inserted into the image after the
394 primary configuration data and before the image data.
395 It is traditional to use the primary configuration file for the RCW
397 (Reset Configuration Word), and the secondary configuration file for
398 any additional PBI commands. However, it is also possible to convert an
399 existing PBI to the above format and “chain” additional data onto the
400 end of the image. This may be especially useful for creating secure
401 boot images.
402 rkimage
404 The primary configuration is the name of the processor to generate the
405 image for. Valid values are:
406 px30
408 rk3036
409 rk3066
410 rk3128
412 rk3188
413 rk322x
414 rk3288
415 rk3308
416 rk3328
417 rk3368
418 rk3399
419 rv1108
420 rk3568
421 spkgimage
423 The primary configuration file consists of lines containing key/value
424 pairs delimited by whitespace. An example follows.
425 # Comments and blank lines may be used
427 key1 value1
428 key2 value2
429 The supported key types are as follows.
431 VERSION
433 NAND_ECC_BLOCK_SIZE
434 NAND_ECC_ENABLE
435 NAND_ECC_SCHEME
436 NAND_BYTES_PER_ECC_BLOCK
437 These all take a positive integer value as their argument. The
438 value will be copied directly into the respective field of the
439 SPKG header structure. For details on these values, refer to
440 Section 7.4 of the Renesas RZ/N1 User's Manual.
441 ADD_DUMMY_BLP
443 Takes a numeric argument, which is treated as a boolean. Any
444 nonzero value will cause a fake BLp security header to be in‐
445 cluded in the SPKG output.
446 PADDING
448 Takes a positive integer value, with an optional K or M suffix,
449 indicating KiB / MiB respectively. The output SPKG file will be
450 padded to a multiple of this value.
451 sunxi_egon
453 The primary configuration is the name to use for the device tree.
454 ublimage
456 The primary configuration is a file containing configuration commands,
457 as documented in doc/README.ublimage of the U-Boot source.
458 zynqimage and zynqmpimage
460 For zynqmpimage, the primary configuration is a file containing the
461 PMUFW (Power Management Unit Firmware). zynqimage does not use the
462 primary configuration.
463 For both image types, the secondary configuration is a file containinig
465 initialization parameters, one per line. Each parameter has the form
466 address data
468 where address and data are hexadecimal integers. The boot ROM will
470 write each data to address when loading the image. At most 256 parame‐
471 ters may be specified in this manner.
472
474 Please report bugs to the U-Boot bug tracker ⟨https://source.denx.de/u-
475 boot/u-boot/issues⟩.
476
478 List image information:
479 mkimage -l uImage
481 Create legacy image with compressed PowerPC Linux kernel:
483 mkimage -A powerpc -O linux -T kernel -C gzip \
485 -a 0 -e 0 -n Linux -d vmlinux.gz uImage
486 Create FIT image with compressed PowerPC Linux kernel:
488 mkimage -f kernel.its kernel.itb
490 Create FIT image with compressed kernel and sign it with keys in the
492 /public/signing-keys directory. Add corresponding public keys into
493 u-boot.dtb, skipping those for which keys cannot be found. Also add a
494 comment.
495 mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \
497 -c "Kernel 3.8 image for production devices" kernel.itb
498 Add public key to u-boot.dtb without needing a FIT to sign. This will
500 also create a FIT containing an images node with no data named un‐
501 used.itb.
502 mkimage -f auto -d /dev/null -k /public/signing-keys -g dev \
504 -o sha256,rsa2048 -K u-boot.dtb unused.itb
505 Add public key with required = "conf" property to u-boot.dtb without
507 needing a FIT to sign. This will also create a useless FIT named un‐
508 used.itb.
509 mkimage -f auto-conf -d /dev/null -k /public/signing-keys -g dev \
511 -o sha256,rsa2048 -K u-boot.dtb -r unused.itb
512 Update an existing FIT image, signing it with additional keys. Add
514 corresponding public keys into u-boot.dtb. This will resign all images
515 with keys that are available in the new directory. Images that request
516 signing with unavailable keys are skipped.
517 mkimage -F -k /secret/signing-keys -K u-boot.dtb \
519 -c "Kernel 3.8 image for production devices" kernel.itb
520 Create a FIT image containing a kernel, using automatic mode. No .its
522 file is required.
523 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
525 -c "Kernel 4.4 image for production devices" -d vmlinuz kernel.itb
526 Create a FIT image containing a kernel and some device tree files, us‐
528 ing automatic mode. No .its file is required.
529 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
531 -c "Kernel 4.4 image for production devices" -d vmlinuz \
532 -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb
533 Create a FIT image containing a signed kernel, using automatic mode. No
535 .its file is required.
536 mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
538 -d vmlinuz -k /secret/signing-keys -g dev -o sha256,rsa2048 kernel.itb
539 Create a FIT image containing a kernel and some device tree files,
541 signing each configuration, using automatic mode. Moreover, the public
542 key needed to verify signatures is added to u-boot.dtb with required =
543 "conf" property.
544 mkimage -f auto-conf -A arm -O linux -T kernel -C none -a 43e00000 \
546 -e 0 -d vmlinuz -b /path/to/file-1.dtb -b /path/to/file-2.dtb \
547 -k /folder/with/signing-keys -g dev -o sha256,rsa2048 \
548 -K u-boot.dtb -r kernel.itb
549
551 dtc(1), dumpimage(1), openssl(1), the U-Boot documentation ⟨https://u-
552 boot.readthedocs.io/en/latest/index.html⟩
553U-Boot 2022-06-11 MKIMAGE(1)