1MKIMAGE(1)                  General Commands Manual                 MKIMAGE(1)
2
3
4

NAME

6       mkimage - generate images for U-Boot
7

SYNOPSIS

9       mkimage [-T type] -l image-file-name
10
11       mkimage [option ...] [-T type] image-file-name
12
13       mkimage [option ...] -f image-tree-source-file|auto|auto-conf image-
14               file-name
15
16       mkimage [option ...] -F image-file-name
17

DESCRIPTION

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
24       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
28       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
34       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

OPTIONS

39   General options
40       -h
41       --help Print a help message and exit.
42
43       -l
44       --list mkimage  lists the information contained in the header of an ex‐
45              isting U-Boot image.
46
47       -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
53       -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
62              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
67       -q
68       --quiet
69              Quiet. Don't print the image header.
70
71       -v
72       --verbose
73              Verbose. Print file names as they are added to the image.
74
75       -V
76       --version
77              Print version information and exit.
78
79   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
86       -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
92       -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
100       -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
105       -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
111       -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
118       -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
124       -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
130                     image-data-file[:image-data-file...]
131
132       -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
138   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
143       -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
149       -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
155       -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
165       -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
170       -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
178       -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
183              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
193       -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
200       -i ramdisk-file
201       --initramfs ramdisk-file
202              Append a ramdisk or initramfs file to the image.
203
204       -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
213       -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
221       -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
229       -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
238       -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
245              The valid values for checksum are:
246
247                     sha1
248                     sha256
249                     sha384
250                     sha512
251
252              The valid values for crypto are:
253
254                     rsa2048
255                     rsa3072
256                     rsa4096
257                     ecdsa256
258
259       -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
269       -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
274       -t
275       --touch
276              Update the timestamp in the FIT.
277
278              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

CONFIGURATION

285       This section documents the formats of the primary and secondary config‐
286       uration options for each image type which supports them.
287
288   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
292              command argument ...
293
294       See TI application report SPRAAG0E ⟨https://www.ti.com/lit/pdf/spraag0
295       for details.
296
297   atmelimage
298       The  primary  configuration is a comma-separated list of NAND Flash pa‐
299       rameters of the form
300
301              parameter=value[,parameter=value...]
302
303       Valid parameters are
304
305              usePmecc
306              nbSectorPerPage
307              spareSize
308              eccBitReq
309              sectorSize
310              eccOffset
311
312       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
315   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
319   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
323   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
327   mtk_image
328       The primary configuration is a semicolon-separated list of  header  op‐
329       tions of the form
330
331              key=value[;key=value...]
332
333       where the valid keys are:
334
335              Key         Description
336              ───────────────────────────────────────────────────────────────────────────
337              lk          If  1,  then an LK (legacy) image header is used. Otherwise, a
338                          BootROM image header is used.
339
340
341
342              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
350       Valid values for media are:
351
352              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
360       Valid values for nandinfo are:
361
362              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
374   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
378   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
383   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
387              value[ value...]
388
389       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
392       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
396       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
403   rkimage
404       The primary configuration is the name of the processor to generate  the
405       image for. Valid values are:
406
407              px30
408              rk3036
409              rk3066
410
411              rk3128
412              rk3188
413              rk322x
414              rk3288
415              rk3308
416              rk3328
417              rk3368
418              rk3399
419              rv1108
420              rk3568
421
422   sunxi_egon
423       The primary configuration is the name to use for the device tree.
424
425   ublimage
426       The  primary configuration is a file containing configuration commands,
427       as documented in doc/README.ublimage of the U-Boot source.
428
429   zynqimage and zynqmpimage
430       For zynqmpimage, the primary configuration is  a  file  containing  the
431       PMUFW  (Power  Management  Unit  Firmware).  zynqimage does not use the
432       primary configuration.
433
434       For both image types, the secondary configuration is a file containinig
435       initialization parameters, one per line. Each parameter has the form
436
437              address data
438
439       where  address  and  data  are  hexadecimal integers. The boot ROM will
440       write each data to address when loading the image. At most 256  parame‐
441       ters may be specified in this manner.
442

BUGS

444       Please report bugs to the U-Boot bug tracker ⟨https://source.denx.de/u-
445       boot/u-boot/issues⟩.
446

EXAMPLES

448       List image information:
449
450              mkimage -l uImage
451
452       Create legacy image with compressed PowerPC Linux kernel:
453
454              mkimage -A powerpc -O linux -T kernel -C gzip \
455                        -a 0 -e 0 -n Linux -d vmlinux.gz uImage
456
457       Create FIT image with compressed PowerPC Linux kernel:
458
459              mkimage -f kernel.its kernel.itb
460
461       Create FIT image with compressed kernel and sign it with  keys  in  the
462       /public/signing-keys  directory.  Add  corresponding  public  keys into
463       u-boot.dtb, skipping those for which keys cannot be found. Also  add  a
464       comment.
465
466              mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \
467                        -c "Kernel 3.8 image for production devices" kernel.itb
468
469       Add  public  key to u-boot.dtb without needing a FIT to sign. This will
470       also create a FIT containing an images node  with  no  data  named  un‐
471       used.itb.
472
473              mkimage -f auto -d /dev/null -k /public/signing-keys -g dev \
474                        -o sha256,rsa2048 -K u-boot.dtb unused.itb
475
476       Add  public  key  with required = "conf" property to u-boot.dtb without
477       needing a FIT to sign. This will also create a useless  FIT  named  un‐
478       used.itb.
479
480              mkimage -f auto-conf -d /dev/null -k /public/signing-keys -g dev \
481                        -o sha256,rsa2048 -K u-boot.dtb -r unused.itb
482
483       Update  an  existing  FIT  image, signing it with additional keys.  Add
484       corresponding public keys into u-boot.dtb. This will resign all  images
485       with  keys that are available in the new directory. Images that request
486       signing with unavailable keys are skipped.
487
488              mkimage -F -k /secret/signing-keys -K u-boot.dtb \
489                        -c "Kernel 3.8 image for production devices" kernel.itb
490
491       Create a FIT image containing a kernel, using automatic mode.  No  .its
492       file is required.
493
494              mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
495                        -c "Kernel 4.4 image for production devices" -d vmlinuz kernel.itb
496
497       Create  a FIT image containing a kernel and some device tree files, us‐
498       ing automatic mode. No .its file is required.
499
500              mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
501                        -c "Kernel 4.4 image for production devices" -d vmlinuz \
502                        -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb
503
504       Create a FIT image containing a signed kernel, using automatic mode. No
505       .its file is required.
506
507              mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \
508                        -d vmlinuz -k /secret/signing-keys -g dev -o sha256,rsa2048 kernel.itb
509
510       Create  a  FIT  image  containing  a kernel and some device tree files,
511       signing each configuration, using automatic mode. Moreover, the  public
512       key  needed to verify signatures is added to u-boot.dtb with required =
513       "conf" property.
514
515              mkimage -f auto-conf -A arm -O linux -T kernel -C none -a 43e00000 \
516                        -e 0 -d vmlinuz -b /path/to/file-1.dtb -b /path/to/file-2.dtb \
517                        -k /folder/with/signing-keys -g dev -o sha256,rsa2048 \
518                        -K u-boot.dtb -r kernel.itb
519

SEE ALSO

521       dtc(1), dumpimage(1), openssl(1), the U-Boot documentation  ⟨https://u-
522       boot.readthedocs.io/en/latest/index.html⟩
523
524
525
526U-Boot                            2022-06-11                        MKIMAGE(1)
Impressum