X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2Fmkimage.1;h=3dcdcedcefafe1346f7fc57c063a438f4b5d9015;hb=45dbb4dd23a0bcbeee66540e5baa85d549ac95fb;hp=f27da6b98bb95ef89abbc53d9c2f07d1cc195f5a;hpb=5aebe3b07254d9ec8f7ae23a4525a6c535a7f858;p=oweals%2Fu-boot.git diff --git a/doc/mkimage.1 b/doc/mkimage.1 index f27da6b98b..3dcdcedcef 100644 --- a/doc/mkimage.1 +++ b/doc/mkimage.1 @@ -4,18 +4,28 @@ mkimage \- Generate image for U-Boot .SH SYNOPSIS .B mkimage -.RB [\fIoptions\fP] +.RB "\-l [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " \-f [" "image tree source file" "]" " [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " \-F [" "uimage file name" "]" + +.B mkimage +.RB [\fIoptions\fP] " (legacy mode)" + .SH "DESCRIPTION" The .B mkimage command is used to create images for use with the U-Boot boot loader. -Thes eimages can contain the linux kernel, device tree blob, root file +These images can contain the linux kernel, device tree blob, root file system image, firmware images etc., either separate or combined. .B mkimage supports two different formats: -The old, +The old .I legacy image format concatenates the individual parts (for example, kernel image, device tree blob and ramdisk image) and adds a 64 bytes header @@ -23,10 +33,11 @@ containing information about target architecture, operating system, image type, compression method, entry points, time stamp, checksums, etc. -The new, +The new .I FIT (Flattened Image Tree) format -allows for more flexibility in handling images of various and also -enhances integrity protection of images with stronger checksums. +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" @@ -59,13 +70,17 @@ Set compression type. Pass \-h as the compression to see the list of supported compression type. .TP -.BI "\-a [" "load addess" "]" +.BI "\-a [" "load address" "]" Set load address with a hex number. .TP .BI "\-e [" "entry point" "]" Set entry point with a hex number. +.TP +.BI "\-l" +List the contents of an image. + .TP .BI "\-n [" "image name" "]" Set image name to 'image name'. @@ -82,16 +97,77 @@ Set XIP (execute in place) flag. .B Create FIT image: .TP -.BI "\-D "dtc option" +.BI "\-b [" "device tree file" "] +Appends the device tree binary file (.dtb) to the FIT. + +.TP +.BI "\-c [" "comment" "]" +Specifies a comment to be added when signing. This is typically a useful +message which describes how the image was signed or some other useful +information. + +.TP +.BI "\-D [" "dtc options" "]" Provide special options to the device tree compiler that is used to create the image. .TP -.BI "\-f "fit-image.its" -Image tree source fine that descbres the structure and contents of the +.BI "\-E +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 'data' property +in each image will be replaced with 'data-offset' and 'data-size' properties. +A 'data-offset' of 0 indicates that it starts in the first (4-byte aligned) +byte after the FIT. + +.TP +.BI "\-f [" "image tree source file" " | " "auto" "]" +Image tree source file that describes the structure and contents of the FIT image. -.SH EXMAPLES +This can be automatically generated for some simple cases. +Use "-f auto" for this. In that case the arguments -d, -A, -O, -T, -C, -a +and -e are used to specify the image to include in the FIT and its attributes. +No .its file is required. + +.TP +.BI "\-F" +Indicates that an existing FIT image should be modified. No dtc +compilation is performed and the \-f flag should not be given. +This can be used to sign images with additional keys after initial image +creation. + +.TP +.BI "\-i [" "ramdisk_file" "]" +Appends the ramdisk file to the FIT. + +.TP +.BI "\-k [" "key_directory" "]" +Specifies the directory containing keys to use for signing. This directory +should contain a private key file .key for use with signing and a +certificate .crt (containing the public key) for use with verification. + +.TP +.BI "\-K [" "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 "\-p [" "external position" "]" +Place external data at a static external position. See \-E. Instead of writing +a 'data-offset' property defining the offset from the end of the FIT, \-p will +use 'data-position' as the absolute position from the base of the FIT. + +.TP +.BI "\-r +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). + +.SH EXAMPLES List image information: .nf @@ -109,10 +185,49 @@ Create FIT image with compressed PowerPC Linux kernel: .nf .B mkimage -f kernel.its kernel.itb .fi +.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. +.nf +.B mkimage -f kernel.its -k /public/signing-keys -K u-boot.dtb \\\\ +.br +.B -c """Kernel 3.8 image for production devices""" kernel.itb +.fi + +.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. +.nf +.B mkimage -F -k /secret/signing-keys -K u-boot.dtb \\\\ +.br +.B -c """Kernel 3.8 image for production devices""" kernel.itb +.fi + +.P +Create a FIT image containing a kernel, using automatic mode. No .its file +is required. +.nf +.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\ +.br +.B -c """Kernel 4.4 image for production devices""" -d vmlinuz kernel.itb +.fi +.P +Create a FIT image containing a kernel and some device tree files, using +automatic mode. No .its file is required. +.nf +.B mkimage -f auto -A arm -O linux -T kernel -C none -a 43e00000 -e 0 \\\\ +.br +.B -c """Kernel 4.4 image for production devices""" -d vmlinuz \\\\ +.B -b /path/to/rk3288-firefly.dtb -b /path/to/rk3288-jerry.dtb kernel.itb +.fi .SH HOMEPAGE http://www.denx.de/wiki/U-Boot/WebHome .PP .SH AUTHOR This manual page was written by Nobuhiro Iwamatsu -and Wolfgang Denk +and Wolfgang Denk . It was updated for image signing by +Simon Glass .