doc/mkimage.1

   1 .TH MKIMAGE 1 "2022-02-07"
   2 .
   3 .SH NAME
   4 mkimage \- generate images for U-Boot
   5 .SH SYNOPSIS
   6 .SY mkimage
   7 .OP \-T type
   8 .BI \-l\~ image-file-name
   9 .YS
  10 .
  11 .SY mkimage
  12 .RI [ option\~ .\|.\|.\&]
  13 .OP \-T type
  14 .I image-file-name
  15 .YS
  16 .
  17 .SY mkimage
  18 .RI [ option\~ .\|.\|.\&]
  19 .BI \-f\~ image-tree-source-file\c
  20 .RB | auto
  21 .I image-file-name
  22 .YS
  23 .
  24 .SY mkimage
  25 .RI [ option\~ .\|.\|.\&]
  26 .BI \-F\~ image-file-name
  27 .YS
  28 .
  29 .SH DESCRIPTION
  30 The
  31 .B mkimage
  32 command is used to create images for use with the U-Boot boot loader.  These
  33 images can contain the Linux kernel, device tree blob, root file system image,
  34 firmware images etc., either separate or combined.
  35 .P
  36 .B mkimage
  37 supports many image formats. Some of these formats may be used by embedded boot
  38 firmware to load U-Boot. Others may be used by U-Boot to load Linux (or some
  39 other kernel):
  40 .P
  41 The legacy image format concatenates the individual parts (for example, kernel
  42 image, device tree blob and ramdisk image) and adds a 64 byte header containing
  43 information about the target architecture, operating system, image type,
  44 compression method, entry points, time stamp, checksums, etc.
  45 .P
  46 The new
  47 .I FIT
  48 (Flattened Image Tree) format allows for more flexibility in handling images of
  49 various types and also enhances integrity protection of images with stronger
  50 checksums. It also supports verified boot.
  51 .
  52 .SH OPTIONS
  53 .
  54 .SS General options
  55 .
  56 .TP
  57 .B \-h
  58 Print a help message and exit.
  59 .
  60 .TP
  61 .B \-l
  62 .B mkimage
  63 lists the information contained in the header of an existing U-Boot image.
  64 .
  65 .TP
  66 .B \-s
  67 Don't copy in the image data. Depending on the image type, this may create
  68 just the header, everything but the image data, or nothing at all.
  69 .
  70 .TP
  71 .BI \-T " image-type"
  72 Parse image file as
  73 .IR image-type .
  74 Pass
  75 .B list
  76 as
  77 .I image-type
  78 to see the list of supported image types. If this option is absent, then it
  79 defaults to
  80 .B kernel
  81 (legacy image). If this option is absent when
  82 .B \-l
  83 is passed, then
  84 .B mkimage
  85 will attempt to automatically detect the image type. Not all image types support
  86 automatic detection, so it may be necessary to pass
  87 .B \-T
  88 explicitly.
  89 .IP
  90 When creating a FIT image with
  91 .BR \-f ,
  92 the image type is always set to
  93 .BR flat_dt .
  94 In this case,
  95 .B \-T
  96 specifies the image node's \(oqtype\(cq property. If
  97 .B \-T
  98 is absent, then the \(oqtype\(cq property will default to
  99 .BR kernel .
 100 .
 101 .TP
 102 .B \-q
 103 Quiet. Don't print the image header.
 104 .
 105 .TP
 106 .B \-v
 107 Verbose. Print file names as they are added to the image.
 108 .
 109 .TP
 110 .B \-V
 111 Print version information and exit.
 112 .
 113 .SS General image-creation options
 114 .
 115 .TP
 116 .BI \-A " architecture"
 117 Set the architecture. Pass
 118 .B \-h
 119 as the architecture to see the list of supported architectures. If
 120 .B \-A
 121 is absent, it defaults to
 122 .BR ppc .
 123 .
 124 .TP
 125 .BI \-O " os"
 126 Set the operating system. The U-Boot
 127 .I bootm
 128 command changes boot method based on the OS type.
 129 Pass
 130 .B \-h
 131 as the
 132 .I os
 133 to see the list of supported OSs. If
 134 .B \-O
 135 is absent, it defaults to
 136 .BR linux .
 137 .
 138 .TP
 139 .BI \-C " compression-type"
 140 Set the compression type. The image data should have already been compressed
 141 using this compression type.
 142 .B mkimage
 143 will not automatically compress image data.
 144 Pass
 145 .B \-h
 146 as the
 147 .I compression-type
 148 to see the list of supported compression types. If
 149 .B \-C
 150 is absent, it defaults to
 151 .BR gzip .
 152 .
 153 .TP
 154 .BI \-a " load-address"
 155 Set the absolute address to load the image data to.
 156 .I load-address
 157 will be interpreted as a hexadecimal number.
 158 .
 159 .TP
 160 .BI \-e " entry-point"
 161 Set the absolute address of the image entry point. The U-Boot
 162 .I bootm
 163 command will jump to this address after loading the image.
 164 .I entry-point
 165 will be interpreted as a hexadecimal number.
 166 .
 167 .TP
 168 .BI \-n " image-name"
 169 Set the image name to
 170 .IR image-name .
 171 .
 172 .TP
 173 .BI \-R " secondary-image-name"
 174 Some image types support a second image for additional data. For these types,
 175 use
 176 .B \-R
 177 to specify this second image.
 178 .TS
 179 allbox;
 180 lb lbx
 181 l l.
 182 Image Type      Secondary Image Description
 183 pblimage        Additional RCW-style header, typically used for PBI commands.
 184 zynqimage, zynqmpimage  T{
 185 Initialization parameters, one per line. Each parameter has the form
 186 .sp
 187 .ti 4
 188 .I address data
 189 .sp
 190 where
 191 .I address
 192 and
 193 .I data
 194 are hexadecimal integers. The boot ROM will write each
 195 .I data
 196 to
 197 .I address
 198 when loading the image. At most 256 parameters may be specified in this
 199 manner.
 200 T}
 201 .TE
 202 .
 203 .TP
 204 .BI \-d " image-data-file"
 205 Use image data from
 206 .IR image-data-file .
 207 If the
 208 .I image-type
 209 is
 210 .BR multi ,
 211 then multiple images may be specified, separated by colons:
 212 .RS
 213 .IP
 214 .IR image-data-file [\fB:\fP image-data-file .\|.\|.]
 215 .RE
 216 .
 217 .TP
 218 .B \-x
 219 Set the
 220 .I XIP
 221 (execute in place) flag. The U-Boot
 222 .I bootm
 223 command will not load the image data, and instead will assume it is already
 224 accessible at the load address (such as via memory-mapped flash).
 225 .
 226 .SS Options for creating FIT images
 227 .
 228 .TP
 229 .BI \-b " device-tree-file"
 230 Appends the device tree binary file (.dtb) to the FIT.
 231 .
 232 .TP
 233 .BI \-c " comment"
 234 Specifies a comment to be added when signing. This is typically a message which
 235 describes how the image was signed or some other useful information.
 236 .
 237 .TP
 238 .BI \-D " dtc-options"
 239 Provide additional options to the device tree compiler when creating the image.
 240 See
 241 .BR dtc (1)
 242 for documentation of possible options. If
 243 .B \-D
 244 is absent, it defaults to
 245 .BR "\-I dts \-O dtb \-p 500" .
 246 .
 247 .TP
 248 .BI \-E
 249 After processing, move the image data outside the FIT and store a data offset
 250 in the FIT. Images will be placed one after the other immediately after the FIT,
 251 with each one aligned to a 4-byte boundary. The existing \(oqdata\(cq property
 252 in each image will be replaced with \(oqdata-offset\(cq and \(oqdata-size\(cq
 253 properties.  A \(oqdata-offset\(cq of 0 indicates that it starts in the first
 254 (4-byte-aligned) byte after the FIT.
 255 .
 256 .TP
 257 .BI \-B " alignment"
 258 The alignment, in hexadecimal, that external data will be aligned to. This
 259 option only has an effect when \-E is specified.
 260 .
 261 .TP
 262 .BI \-p " external-position"
 263 Place external data at a static external position. Instead of writing a
 264 \(oqdata-offset\(cq property defining the offset from the end of the FIT,
 265 .B \-p
 266 will use \(oqdata-position\(cq as the absolute position from the base of the
 267 FIT. See
 268 .B \-E
 269 for details on using external data.
 270 .
 271 .TP
 272 \fB\-f \fIimage-tree-source-file\fR | \fBauto
 273 Image tree source file that describes the structure and contents of the
 274 FIT image.
 275 .IP
 276 In some simple cases, the image tree source can be generated automatically. To
 277 use this feature, pass
 278 .BR "\-f auto" .
 279 The
 280 .BR \-d ,
 281 .BR \-A ,
 282 .BR \-O ,
 283 .BR \-T ,
 284 .BR \-C ,
 285 .BR \-a ,
 286 and
 287 .B \-e
 288 options may be used to specify the image to include in the FIT and its
 289 attributes. No
 290 .I image-tree-source-file
 291 is required.
 292 .
 293 .TP
 294 .B \-F
 295 Indicates that an existing FIT image should be modified. No dtc compilation will
 296 be performed and
 297 .B \-f
 298 should not be passed. This can be used to sign images with additional keys
 299 after initial image creation.
 300 .
 301 .TP
 302 .BI \-i " ramdisk-file"
 303 Append a ramdisk or initramfs file to the image.
 304 .
 305 .TP
 306 .BI \-k " key-directory"
 307 Specifies the directory containing keys to use for signing. This directory
 308 should contain a private key file
 309 .IR name .key
 310 for use with signing, and a certificate
 311 .IR name .crt
 312 (containing the public key) for use with verification. The public key is only
 313 necessary when embedding it into another device tree using
 314 .BR \-K .
 315 .I name
 316 defaults to the value of the signature node's \(oqkey-name-hint\(cq property,
 317 but may be overridden using
 318 .BR \-g .
 319 .
 320 .TP
 321 .BI \-G " key-file"
 322 Specifies the private key file to use when signing. This option may be used
 323 instead of \-k.
 324 .
 325 .TP
 326 .BI \-K " key-destination"
 327 Specifies a compiled device tree binary file (typically .dtb) to write
 328 public key information into. When a private key is used to sign an image,
 329 the corresponding public key is written into this file for for run-time
 330 verification. Typically the file here is the device tree binary used by
 331 CONFIG_OF_CONTROL in U-Boot.
 332 .
 333 .TP
 334 .BI \-g " key-name-hint"
 335 Overrides the signature node's \(oqkey-name-hint\(cq property. This is
 336 especially useful when signing an image with
 337 .BR "\-f auto" .
 338 This is the
 339 .I name
 340 part of the key. The directory part is set by
 341 .BR \-k .
 342 This option also indicates that the images included in the FIT should be signed.
 343 If this option is specified, then
 344 .B \-o
 345 must be specified as well.
 346 .
 347 .TP
 348 .BI \-o " crypto" , checksum
 349 Specifies the algorithm to be used for signing a FIT image. The default is
 350 taken from the signature node's \(oqalgo\(cq property.
 351 The valid values for
 352 .I crypto
 353 are:
 354 .RS
 355 .IP
 356 .TS
 357 lb.
 358 rsa2048
 359 rsa3072
 360 rsa4096
 361 ecdsa256
 362 .TE
 363 .RE
 364 .IP
 365 The valid values for
 366 .I checksum
 367 are
 368 .RS
 369 .IP
 370 .TS
 371 lb.
 372 sha1
 373 sha256
 374 sha384
 375 sha512
 376 .TE
 377 .RE
 378 .
 379 .TP
 380 .B \-r
 381 Specifies that keys used to sign the FIT are required. This means that they
 382 must be verified for the image to boot. Without this option, the verification
 383 will be optional (useful for testing but not for release).
 384 .
 385 .TP
 386 .BI \-N " engine"
 387 The openssl engine to use when signing and verifying the image. For a complete
 388 list of available engines, refer to
 389 .BR engine (1).
 390 .
 391 .TP
 392 .B \-t
 393 Update the timestamp in the FIT.
 394 .IP
 395 Normally the FIT timestamp is created the first time mkimage runs,
 396 when converting the source .its to the binary .fit file. This corresponds to
 397 using
 398 .BR -f .
 399 But if the original input to mkimage is a binary file (already compiled), then
 400 the timestamp is assumed to have been set previously.
 401 .
 402 .SH EXAMPLES
 403 .\" Reduce the width of the tab stops to something reasonable
 404 .ta T 1i
 405 List image information:
 406 .RS
 407 .P
 408 .EX
 409 \fBmkimage \-l uImage
 410 .EE
 411 .RE
 412 .P
 413 Create legacy image with compressed PowerPC Linux kernel:
 414 .RS
 415 .P
 416 .EX
 417 \fBmkimage \-A powerpc \-O linux \-T kernel \-C gzip \\
 418         \-a 0 \-e 0 \-n Linux \-d vmlinux.gz uImage
 419 .EE
 420 .RE
 421 .P
 422 Create FIT image with compressed PowerPC Linux kernel:
 423 .RS
 424 .P
 425 .EX
 426 \fBmkimage \-f kernel.its kernel.itb
 427 .EE
 428 .RE
 429 .P
 430 Create FIT image with compressed kernel and sign it with keys in the
 431 /public/signing\-keys directory. Add corresponding public keys into u\-boot.dtb,
 432 skipping those for which keys cannot be found. Also add a comment.
 433 .RS
 434 .P
 435 .EX
 436 \fBmkimage \-f kernel.its \-k /public/signing\-keys \-K u\-boot.dtb \\
 437         \-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
 438 .EE
 439 .RE
 440 .P
 441 Add public keys to u\-boot.dtb without needing a FIT to sign. This will also
 442 create a FIT containing an images node with no data named unused.itb.
 443 .RS
 444 .P
 445 .EX
 446 \fBmkimage \-f auto \-d /dev/null \-k /public/signing\-keys \-g dev \\
 447         \-o sha256,rsa2048 \-K u\-boot.dtb unused.itb
 448 .EE
 449 .RE
 450 .P
 451 Update an existing FIT image, signing it with additional keys.
 452 Add corresponding public keys into u\-boot.dtb. This will resign all images
 453 with keys that are available in the new directory. Images that request signing
 454 with unavailable keys are skipped.
 455 .RS
 456 .P
 457 .EX
 458 \fBmkimage \-F \-k /secret/signing\-keys \-K u\-boot.dtb \\
 459         \-c \(dqKernel 3.8 image for production devices\(dq kernel.itb
 460 .EE
 461 .RE
 462 .P
 463 Create a FIT image containing a kernel, using automatic mode. No .its file
 464 is required.
 465 .RS
 466 .P
 467 .EX
 468 \fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
 469         \-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz kernel.itb
 470 .EE
 471 .RE
 472 .P
 473 Create a FIT image containing a kernel and some device tree files, using
 474 automatic mode. No .its file is required.
 475 .RS
 476 .P
 477 .EX
 478 \fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
 479         \-c \(dqKernel 4.4 image for production devices\(dq \-d vmlinuz \\
 480         \-b /path/to/rk3288\-firefly.dtb \-b /path/to/rk3288\-jerry.dtb kernel.itb
 481 .EE
 482 .RE
 483 .P
 484 Create a FIT image containing a signed kernel, using automatic mode. No .its
 485 file is required.
 486 .RS
 487 .P
 488 .EX
 489 \fBmkimage \-f auto \-A arm \-O linux \-T kernel \-C none \-a 43e00000 \-e 0 \\
 490         \-d vmlinuz \-k /secret/signing\-keys \-g dev \-o sha256,rsa2048 kernel.itb
 491 .EE
 492 .RE
 493 .
 494 .SH HOMEPAGE
 495 http://www.denx.de/wiki/U-Boot/WebHome
 496 .PP
 497 .SH AUTHOR
 498 This manual page was written by Nobuhiro Iwamatsu <iwamatsu@nigauri.org>
 499 and Wolfgang Denk <wd@denx.de>. It was updated for image signing by
 500 Simon Glass <sjg@chromium.org>.