summaryrefslogtreecommitdiff
path: root/doc/mkimage.1
blob: 353ea8b2f761e747daa92a998b12b8fdbf5099e7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
.\" SPDX-License-Identifier: GPL-2.0
.\" Copyright (C) 2022 Sean Anderson <seanga2@gmail.com>
.\" Copyright (C) 2013-20 Simon Glass <sjg@chromium.org>
.\" Copyright (C) 2010 Nobuhiro Iwamatsu <iwamatsu@nigauri.org>
.\" Copyright (C) 2010 Wolfgang Denk <wd@denx.de>
.TH MKIMAGE 1 2022-06-11 U-Boot
.
.SH NAME
mkimage \- generate images for U-Boot
.SH SYNOPSIS
.SY mkimage
.OP \-T type
.BI \-l\~ image-file-name
.YS
.
.SY mkimage
.RI [ option\~ .\|.\|.\&]
.OP \-T type
.I image-file-name
.YS
.
.SY mkimage
.RI [ option\~ .\|.\|.\&]
.BI \-f\~ image-tree-source-file\c
.RB | auto
.I image-file-name
.YS
.
.SY mkimage
.RI [ option\~ .\|.\|.\&]
.BI \-F\~ image-file-name
.YS
.
.SH DESCRIPTION
The
.B mkimage
command is used to create images for use with the U-Boot boot loader.  These
images can contain the Linux kernel, device tree blob, root file system image,
firmware images etc., either separate or combined.
.P
.B mkimage
supports many image formats. Some of these formats may be used by embedded boot
firmware to load U-Boot. Others may be used by U-Boot to load Linux (or some
other kernel):
.P
The legacy image format concatenates the individual parts (for example, kernel
image, device tree blob and ramdisk image) and adds a 64 byte header containing
information about the target architecture, operating system, image type,
compression method, entry points, time stamp, checksums, etc.
.P
The new
.I FIT
(Flattened Image Tree) format allows for more flexibility in handling images of
various types and also enhances integrity protection of images with stronger
checksums. It also supports verified boot.
.
.SH OPTIONS
.
.SS General options
.
.TP
.B \-h
.TQ
.B \-\-help
Print a help message and exit.
.
.TP
.B \-l
.TQ
.B \-\-list
.B mkimage
lists the information contained in the header of an existing U-Boot image.
.
.TP
.B \-s
.TQ
.B \-\-no\-copy
Don't copy in the image data. Depending on the image type, this may create
just the header, everything but the image data, or nothing at all.
.
.TP
.BI \-T " image-type"
.TQ
.BI \-\-type " image-type"
Parse image file as
.IR image-type .
Pass
.B list
as
.I image-type
to see the list of supported image types. If this option is absent, then it
defaults to
.B kernel
(legacy image). If this option is absent when
.B \-l
is passed, then
.B mkimage
will attempt to automatically detect the image type. Not all image types support
automatic detection, so it may be necessary to pass
.B \-T
explicitly.
.IP
When creating a FIT image with
.BR \-f ,
the image type is always set to
.BR flat_dt .
In this case,
.B \-T
specifies the image node's \(oqtype\(cq property. If
.B \-T
is absent, then the \(oqtype\(cq property will default to
.BR kernel .
.
.TP
.B \-q
.TQ
.B \-\-quiet
Quiet. Don't print the image header.
.
.TP
.B \-v
.TQ
.B \-\-verbose
Verbose. Print file names as they are added to the image.
.
.TP
.B \-V
.TQ
.B \-\-version
Print version information and exit.
.
.SS General image-creation options
.
.TP
.BI \-A " architecture"
.TQ
.BI \-\-architecture " architecture"
Set the architecture. Pass
.B \-h
as the architecture to see the list of supported architectures. If
.B \-A
is absent, it defaults to
.BR ppc .
.
.TP
.BI \-O " os"
.TQ
.BI \-\-os " os"
Set the operating system. The U-Boot
.I bootm
command changes boot method based on the OS type.
Pass
.B \-h
as the
.I os
to see the list of supported OSs. If
.B \-O
is absent, it defaults to
.BR linux .
.
.TP
.BI \-C " compression-type"
.TQ
.BI \-\-compression " compression-type"
Set the compression type. The image data should have already been compressed
using this compression type.
.B mkimage
will not automatically compress image data.
Pass
.B \-h
as the
.I compression-type
to see the list of supported compression types. If
.B \-C
is absent, it defaults to
.BR gzip .
.
.TP
.BI \-a " load-address"
.TQ
.BI \-\-load\-address " load-address"
Set the absolute address to load the image data to.
.I load-address
will be interpreted as a hexadecimal number.
.
.TP
.BI \-e " entry-point"
.TQ
.BI \-\-entry\-point " entry-point"
Set the absolute address of the image entry point. The U-Boot
.I bootm
command will jump to this address after loading the image.
.I entry-point
will be interpreted as a hexadecimal number.
.
.TP
.BI \-n " primary-configuration"
.TQ
.BI \-\-config " primary-configuration"
Images may require additional configuration not specified with other options,
often in a image-type-specific format. The image types which support this
option and the format of their configuration are listed in
.BR CONFIGURATION .
.
.TP
.BI \-R " secondary-configuration"
.TQ
.BI \-\-secondary\-config " secondary-configuration"
Some image types support a second set of configuration data. The image types
which support secondary configuration and the formap of their configuration are
listed in
.BR CONFIGURATION .
.
.TP
.BI \-d " image-data-file"
.TQ
.BI \-\-image " image-data-file"
Use image data from
.IR image-data-file .
If the
.I image-type
is
.BR multi ,
then multiple images may be specified, separated by colons:
.RS
.IP
.IR image-data-file [\fB:\fP image-data-file .\|.\|.]
.RE
.
.TP
.B \-x
.TQ
.B \-\-xip
Set the
.I XIP
(execute in place) flag. The U-Boot
.I bootm
command will not load the image data, and instead will assume it is already
accessible at the load address (such as via memory-mapped flash).
.
.SS Options for creating FIT images
.
.TP
.BI \-b " device-tree-file"
.TQ
.BI \-\-device\-tree " device-tree-file"
Appends the device tree binary file (.dtb) to the FIT.
.
.TP
.BI \-c " comment"
.TQ
.BI \-\-comment " comment"
Specifies a comment to be added when signing. This is typically a message which
describes how the image was signed or some other useful information.
.
.TP
.BI \-D " dtc-options"
.TQ
.BI \-\-dtcopts " dtc-options"
Provide additional options to the device tree compiler when creating the image.
See
.BR dtc (1)
for documentation of possible options. If
.B \-D
is absent, it defaults to
.BR "\-I dts \-O dtb \-p 500" .
.
.TP
.BI \-E
.TQ
.BI \-\-external
After processing, move the image data outside the FIT and store a data offset
in the FIT. Images will be placed one after the other immediately after the FIT,
with each one aligned to a 4-byte boundary. The existing \(oqdata\(cq property
in each image will be replaced with \(oqdata-offset\(cq and \(oqdata-size\(cq
properties.  A \(oqdata-offset\(cq of 0 indicates that it starts in the first
(4-byte-aligned) byte after the FIT.
.
.TP
.BI \-B " alignment"
.TQ
.BI \-\-alignment " alignment"
The alignment, in hexadecimal, that external data will be aligned to. This
option only has an effect when \-E is specified.
.
.TP
.BI \-p " external-position"
.TQ
.BI \-\-position " external-position"
Place external data at a static external position. Instead of writing a
\(oqdata-offset\(cq property defining the offset from the end of the FIT,
.B \-p
will use \(oqdata-position\(cq as the absolute position from the base of the
FIT. See
.B \-E
for details on using external data.
.
.TP
\fB\-f \fIimage-tree-source-file\fR | \fBauto
.TQ
\fB\-\-fit \fIimage-tree-source-file\fR | \fBauto
Image tree source file that describes the structure and contents of the
FIT image.
.IP
In some simple cases, the image tree source can be generated automatically. To
use this feature, pass
.BR "\-f auto" .
The
.BR \-d ,
.BR \-A ,
.BR \-O ,
.BR \-T ,
.BR \-C ,
.BR \-a ,
and
.B \-e
options may be used to specify the image to include in the FIT and its
attributes. No
.I image-tree-source-file
is required.
.
.TP
.B \-F
.TQ
.B \-\-update
Indicates that an existing FIT image should be modified. No dtc compilation will
be performed and
.B \-f
should not be passed. This can be used to sign images with additional keys
after initial image creation.
.
.TP
.BI \-i " ramdisk-file"
.TQ
.BI \-\-initramfs " ramdisk-file"
Append a ramdisk or initramfs file to the image.
.
.TP
.BI \-k " key-directory"
.TQ
.BI \-\-key\-dir " key-directory"
Specifies the directory containing keys to use for signing. This directory
should contain a private key file
.IR name .key
for use with signing, and a certificate
.IR name .crt
(containing the public key) for use with verification. The public key is only
necessary when embedding it into another device tree using
.BR \-K .
.I name
defaults to the value of the signature node's \(oqkey-name-hint\(cq property,
but may be overridden using
.BR \-g .
.
.TP
.BI \-G " key-file"
.TQ
.BI \-\-key\-file " key-file"
Specifies the private key file to use when signing. This option may be used
instead of \-k.
.
.TP
.BI \-K " key-destination"
.TQ
.BI \-\-key\-dest " key-destination"
Specifies a compiled device tree binary file (typically .dtb) to write
public key information into. When a private key is used to sign an image,
the corresponding public key is written into this file for for run-time
verification. Typically the file here is the device tree binary used by
CONFIG_OF_CONTROL in U-Boot.
.
.TP
.BI \-g " key-name-hint"
.TQ
.BI \-\-key\-name\-hint " key-name-hint"
Overrides the signature node's \(oqkey-name-hint\(cq property. This is
especially useful when signing an image with
.BR "\-f auto" .
This is the
.I name
part of the key. The directory part is set by
.BR \-k .
This option also indicates that the images included in the FIT should be signed.
If this option is specified, then
.B \-o
must be specified as well.
.
.TP
.BI \-o " crypto" , checksum
.TQ
.BI \-\-algo " crypto" , checksum
Specifies the algorithm to be used for signing a FIT image. The default is
taken from the signature node's \(oqalgo\(cq property.
The valid values for
.I crypto
are:
.RS
.IP
.TS
lb.
rsa2048
rsa3072
rsa4096
ecdsa256
.TE
.RE
.IP
The valid values for
.I checksum
are
.RS
.IP
.TS
lb.
sha1
sha256
sha384
sha512
.TE
.RE
.
.TP
.B \-r
.TQ
.B \-\-key\-required
Specifies that keys used to sign the FIT are required. This means that they
must be verified for the image to boot. Without this option, the verification
will be optional (useful for testing but not for release).
.
.TP
.BI \-N " engine"
.TQ
.BI \-\-engine " engine"
The openssl engine to use when signing and verifying the image. For a complete
list of available engines, refer to
.BR engine (1).
.
.TP
.B \-t
.TQ
.B \-\-touch
Update the timestamp in the FIT.
.IP
Normally the FIT timestamp is created the first time mkimage runs,
when converting the source .its to the binary .fit file. This corresponds to
using
.BR -f .
But if the original input to mkimage is a binary file (already compiled), then
the timestamp is assumed to have been set previously.
.
.SH CONFIGURATION
This section documents the formats of the primary and secondary configuration
options for each image type which supports them.
.
.SS aisimage
The primary configuration is a file containing a series of
.I AIS
(Application Image Script) commands, one per line. Each command has the form
.RS
.P
.IR "command argument " .\|.\|.
.RE
.P
See
.UR https://\:www\:.ti\:.com/\:lit/\:pdf/\:spraag0
TI application report SPRAAG0E
.UE
for details.
.
.SS atmelimage
The primary configuration is a comma-separated list of NAND Flash parameters of
the form
.RS
.P
\fIparameter\fB=\fIvalue\fR[\fB,\fIparameter\fB=\fIvalue\fR.\|.\|.\&]
.RE
.P
Valid
.IR parameter s
are
.RS
.P
.TS
lb.
usePmecc
nbSectorPerPage
spareSize
eccBitReq
sectorSize
eccOffset
.TE
.RE
.P
and valid
.IR value s
are decimal numbers. See section 11.4.4.1 of the SAMA5D3 Series Data Sheet for
valid values for each parameter.
.
.SS imximage
The primary configuration is a file containing configuration commands, as
documented in doc/\:imx/\:mkimage/\:imximage.txt of the U-Boot source.
.
.SS imx8image and imx8mimage
The primary configuration is a file containing configuration commands, as
documented in doc/\:imx/\:mkimage/\:imx8image.txt of the U-Boot source.
.
.SS kwbimage
The primary configuration is a file containing configuration commands, as
documented in doc/\:imx/\:mkimage/\:kwbimage.txt of the U-Boot source.
.
.SS mtk_image
The primary configuration is a semicolon-separated list of header options of the
form
.RS
.P
\fIkey\fB=\fIvalue\fR[\fB;\fIkey\fB=\fIvalue\fR.\|.\|.\&]
.RE
.P
where the valid keys are:
.RS
.P
.TS
lb lbx
lb l.
Key	Description
_
lk	T{
If \fB1\fP, then an \fILK\fP (legacy) image header is used. Otherwise, a
\fIBootROM\fP image header is used.
T}
lkname	T{
The name of the LK image header. The maximum length is 32 ASCII characters. If
not specified, the default value is \fBU-Boot\fP.
T}
media	The boot device. See below for valid values.
nandinfo	The desired NAND device type. See below for valid values.
arm64	If \fB1\fP, then this denotes an AArch64 image.
hdroffset	Increase the reported size of the BRLYT header by this amount.
.TE
.RE
.P
Valid values for
.B media
are:
.RS
.P
.TS
lb lb
lb l.
Value	Description
_
nand	Parallel NAND flash
snand	Serial NAND flash
nor	Serial NOR flash
emmc	\fIeMMC\fP (Embedded Multi-Media Card)
sdmmc	\fISD\fP (Secure Digital) card
.TE
.RE
.P
Valid values for
.B nandinfo
are:
.RS
.P
.TS
lb lb lb	lb	lb
lb l	l	l	l.
Value	NAND type	Page size	OOB size	Total size
_
2k+64	Serial	2KiB	64B
2k+120	Serial	2KiB	120B
2k+128	Serial	2KiB	128B
4k+256	Serial	4KiB	256B
1g:2k+64	Parallel	2KiB	64B	1Gbit
2g:2k+64	Parallel	2KiB	64B	2Gbit
4g:2k+64	Parallel	2KiB	64B	4Gbit
2g:2k+128	Parallel	2KiB	128B	2Gbit
4g:2k+128	Parallel	2KiB	128B	4Gbit
.TE
.RE
.
.SS mxsimage
The primary configuration is a file containing configuration commands, as
documented in doc/\:imx/\:mkimage/\:mxsimage.txt of the U-Boot source.
.
.SS omapimage
The primary configuration is the optional value
.BR byteswap .
If present, each 32-bit word of the image will have its bytes swapped
(converting from little-endian to big-endian, or vice versa).
.
.SS pblimage
The primary configuration is a file containing the
.I PBI
(Pre-Boot Image) header. Each line of the configuration has the format
.RS
.P
.IR value "[ " value .\|.\|.\&]
.RE
.P
Where
.I value
is a 32-bit hexadecimal integer. Each
.I value
will, after being converted to raw bytes, be literally prepended to the PBI.
.P
The secondary configuration is a file with the same format as the primary
configuration file. It will be inserted into the image after the primary
configuration data and before the image data.
.P
It is traditional to use the primary configuration file for the
.I RCW
(Reset Configuration Word), and the secondary configuration file for any
additional PBI commands. However, it is also possible to convert an existing PBI
to the above format and \(lqchain\(rq additional data onto the end of the
image. This may be especially useful for creating secure boot images.
.
.SS rkimage
The primary configuration is the name of the processor to generate the image
for. Valid values are:
.RS
.P
.TS
lb.
px30
rk3036
rk3066
rk3128
rk3188
rk322x
rk3288
rk3308
rk3328
rk3368
rk3399
rv1108
rk3568
.TE
.RE
.
.SS sunxi_egon
The primary configuration is the name to use for the device tree.
.
.SS ublimage
The primary configuration is a file containing configuration commands, as
documented in doc/\:README.ublimage of the U-Boot source.
.
.SS zynqimage and zynqmpimage
For
.BR zynqmpimage ,
the primary configuration is a file containing the
.I PMUFW
(Power Management Unit Firmware).
.B zynqimage
does not use the primary configuration.
.P
For both image types, the secondary configuration is a file containinig
initialization parameters, one per line. Each parameter has the form
.RS
.P
.I address data
.RE
.P
where
.I address
and
.I data
are hexadecimal integers. The boot ROM will write each
.I data
to
.I address
when loading the image. At most 256 parameters may be specified in this
manner.
.
.SH BUGS
Please report bugs to the
.UR https://\:source\:.denx\:.de/\:u-boot/\:u-boot/\:issues
U-Boot bug tracker
.UE .
.SH EXAMPLES
.\" Reduce the width of the tab stops to something reasonable
.ta T 1i
List image information:
.RS
.P
.EX
\fBmkimage \-l uImage
.EE
.RE
.P
Create legacy image with compressed PowerPC Linux kernel:
.RS
.P
.EX
\fBmkimage \-A powerpc \-O linux \-T kernel \-C gzip \\
	\-a 0 \-e 0 \-n Linux \-d vmlinux.gz uImage
.EE
.RE
.P
Create FIT image with compressed PowerPC Linux kernel:
.RS
.P
.EX
\fBmkimage \-f kernel.its kernel.itb
.EE
.RE
.P
Create FIT image with compressed kernel and sign it with keys in the
/public/signing\-keys directory. Add corresponding public keys into u\-boot.dtb,
skipping those for which keys cannot be found. Also add a comment.
.RS
.P
.EX
\fBmkimage \-f kernel.its \-k /public/signing\-keys \-K u\-boot.dtb \\
	\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
.EE
.RE
.P
Add public keys to u\-boot.dtb without needing a FIT to sign. This will also
create a FIT containing an images node with no data named unused.itb.
.RS
.P
.EX
\fBmkimage \-f auto \-d /dev/null \-k /public/signing\-keys \-g dev \\
	\-o sha256,rsa2048 \-K u\-boot.dtb unused.itb
.EE
.RE
.P
Update an existing FIT image, signing it with additional keys.
Add corresponding public keys into u\-boot.dtb. This will resign all images
with keys that are available in the new directory. Images that request signing
with unavailable keys are skipped.
.RS
.P
.EX
\fBmkimage \-F \-k /secret/signing\-keys \-K u\-boot.dtb \\
	\-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
.EE
.RE
.P
Create a FIT image containing a kernel, using automatic mode. No .its file
is required.
.RS
.P
.EX
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
	\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz kernel.itb
.EE
.RE
.P
Create a FIT image containing a kernel and some device tree files, using
automatic mode. No .its file is required.
.RS
.P
.EX
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
	\-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz \\
	\-b /path/to/rk3288\-firefly.dtb \-b /path/to/rk3288\-jerry.dtb kernel.itb
.EE
.RE
.P
Create a FIT image containing a signed kernel, using automatic mode. No .its
file is required.
.RS
.P
.EX
\fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
	\-d vmlinuz \-k /secret/signing\-keys \-g dev \-o sha256,rsa2048 kernel.itb
.EE
.RE
.
.SH SEE ALSO
.BR dtc (1),
.BR dumpimage (1),
.BR openssl (1),
the\~
.UR https://\:u-boot\:.readthedocs\:.io/\:en/\:latest/\:index.html
U-Boot documentation
.UE