doc/mkeficapsule.1

   1 .\" SPDX-License-Identifier: GPL-2.0+
   2 .\" Copyright (c) 2021, Linaro Limited
   3 .\"             written by AKASHI Takahiro <[email protected]>
   4 .TH MAEFICAPSULE 1 "May 2021"
   5
   6 .SH NAME
   7 mkeficapsule \- Generate EFI capsule file for U-Boot
   8
   9 .SH SYNOPSIS
  10 .B mkeficapsule
  11 .RI [ options ] " " [ image-blob ] " " capsule-file
  12
  13 .B mkeficapsule
  14 .RI guidgen " " [ GUID ] " " DTB " " IMAGE_NAME...
  15
  16 .SH "DESCRIPTION"
  17 The
  18 .B mkeficapsule
  19 command is used to create an EFI capsule file to be used by U-Boot for firmware
  20 updates.
  21 A capsule file may contain various types of firmware blobs which are to be
  22 applied to the system.
  23 If a capsule file is placed in the /EFI/CapusuleUpdate directory of the EFI
  24 system partition, U-Boot will try to execute the update at the next reboot.
  25
  26 Optionally, a capsule file can be signed with a given private key.
  27 In this case, the update will be authenticated by verifying the signature
  28 before applying.
  29
  30 Additionally, an empty capsule file can be generated to indicate the acceptance
  31 or rejection of firmware images by a governing component like an operating
  32 system.
  33 Empty capsules do not require an image-blob input file.
  34
  35 .B mkeficapsule
  36 takes any type of image files when generating non empty capsules, including:
  37 .TP
  38 .I raw image
  39 format is a single binary blob of any type of firmware.
  40
  41 .TP
  42 .I FIT (Flattened Image Tree) image
  43 format is the same as used in the new uImage format and allows for
  44 multiple binary blobs in a single capsule file.
  45 This type of image file can be generated by
  46 .BR mkimage .
  47
  48 mkeficapsule can also be used to simulate the dynamic GUID generation used to
  49 identify firmware images in capsule updates by providing the namespace guid, dtb
  50 for the board, and a list of firmware images.
  51
  52 .SH "OPTIONS"
  53
  54 .TP
  55 .BI "-g\fR,\fB --guid " guid-string
  56 Specify guid for image blob type. The format is:
  57     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  58
  59 The first three elements are in little endian, while the rest
  60 is in big endian. The option must be specified for all non empty and
  61 image acceptance capsules
  62
  63 .TP
  64 .BI "-i\fR,\fB --index " index
  65 Specify an image index
  66
  67 .TP
  68 .BI "-I\fR,\fB --instance " instance
  69 Specify a hardware instance
  70
  71 .PP
  72 FMP Payload Header is inserted right before the payload if
  73 .BR --fw-version
  74 is specified
  75
  76
  77 .TP
  78 .BI "-v\fR,\fB --fw-version " firmware-version
  79 Specify a firmware version, 0 if omitted
  80
  81 .PP
  82 For generation of firmware accept empty capsule
  83 .BR --guid
  84 is mandatory
  85 .TP
  86 .BI "-A\fR,\fB --fw-accept "
  87 Generate a firmware acceptance empty capsule
  88
  89 .TP
  90 .BI "-R\fR,\fB --fw-revert "
  91 Generate a firmware revert empty capsule
  92
  93 .TP
  94 .BI "-o\fR,\fB --capoemflag "
  95 Capsule OEM flag, value between 0x0000 to 0xffff
  96
  97 .TP
  98 .BR -V ", " --version
  99 Print version information and exit.
 100
 101 .TP
 102 .BR -h ", " --help
 103 Print a help message
 104
 105 .PP
 106 With signing,
 107 .BR --private-key ", " --certificate " and " --monotonic-count
 108 are all mandatory.
 109
 110 .TP
 111 .BI "-p\fR,\fB --private-key " private-key-file
 112 Specify signer's private key file in PEM
 113
 114 .TP
 115 .BI "-c\fR,\fB --certificate " certificate-file
 116 Specify signer's certificate file in EFI certificate list format
 117
 118 .TP
 119 .BI "-m\fR,\fB --monotonic-count " count
 120 Specify a monotonic count which is set to be monotonically incremented
 121 at every firmware update.
 122
 123 .TP
 124 .B "-d\fR,\fB --dump_sig"
 125 Dump signature data into *.p7 file
 126
 127 .SH "GUIDGEN OPTIONS"
 128
 129 .TP
 130 .B "[GUID]"
 131 The namespace/salt GUID, by default this is EFI_CAPSULE_NAMESPACE_GUID.
 132 The format is:
 133     xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 134
 135 .TP
 136 .B DTB
 137 The device tree blob file for the board.
 138
 139 .TP
 140 .B IMAGE_NAME...
 141 The names of the firmware images to generate GUIDs for.
 142
 143 .PP
 144 .SH FILES
 145 .TP
 146 .I /EFI/UpdateCapsule
 147 The directory in which all capsule files be placed
 148
 149 .SH SEE ALSO
 150 .BR mkimage (1)
 151
 152 .SH AUTHORS
 153 Written by AKASHI Takahiro <[email protected]>
 154
 155 .SH HOMEPAGE
 156 http://www.u-boot.org/