doc/mkeficapsule.1

.\" SPDX-License-Identifier: GPL-2.0+
.\" Copyright (c) 2021, Linaro Limited
.\" 		written by AKASHI Takahiro <takahiro.akashi@linaro.org>
.TH MAEFICAPSULE 1 "May 2021"

.SH NAME
mkeficapsule \- Generate EFI capsule file for U-Boot

.SH SYNOPSIS
.B mkeficapsule
.RI [ options ] " " [ image-blob ] " " capsule-file

.B mkeficapsule
.RI guidgen " " [ GUID ] " " DTB " " IMAGE_NAME...

.SH "DESCRIPTION"
The
.B mkeficapsule
command is used to create an EFI capsule file to be used by U-Boot for firmware
updates.
A capsule file may contain various types of firmware blobs which are to be
applied to the system.
If a capsule file is placed in the /EFI/CapusuleUpdate directory of the EFI
system partition, U-Boot will try to execute the update at the next reboot.

Optionally, a capsule file can be signed with a given private key.
In this case, the update will be authenticated by verifying the signature
before applying.

Additionally, an empty capsule file can be generated to indicate the acceptance
or rejection of firmware images by a governing component like an operating
system.
Empty capsules do not require an image-blob input file.

.B mkeficapsule
takes any type of image files when generating non empty capsules, including:
.TP
.I raw image
format is a single binary blob of any type of firmware.

.TP
.I FIT (Flattened Image Tree) image
format is the same as used in the new uImage format and allows for
multiple binary blobs in a single capsule file.
This type of image file can be generated by
.BR mkimage .

mkeficapsule can also be used to simulate the dynamic GUID generation used to
identify firmware images in capsule updates by providing the namespace guid, dtb
for the board, and a list of firmware images.

.SH "OPTIONS"

.TP
.BI "-g\fR,\fB --guid " guid-string
Specify guid for image blob type. The format is:
    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

The first three elements are in little endian, while the rest
is in big endian. The option must be specified for all non empty and
image acceptance capsules

.TP
.BI "-i\fR,\fB --index " index
Specify an image index

.TP
.BI "-I\fR,\fB --instance " instance
Specify a hardware instance

.PP
FMP Payload Header is inserted right before the payload if
.BR --fw-version
is specified


.TP
.BI "-v\fR,\fB --fw-version " firmware-version
Specify a firmware version, 0 if omitted

.PP
For generation of firmware accept empty capsule
.BR --guid
is mandatory
.TP
.BI "-A\fR,\fB --fw-accept "
Generate a firmware acceptance empty capsule

.TP
.BI "-R\fR,\fB --fw-revert "
Generate a firmware revert empty capsule

.TP
.BI "-o\fR,\fB --capoemflag "
Capsule OEM flag, value between 0x0000 to 0xffff

.TP
.BR -V ", " --version
Print version information and exit.

.TP
.BR -h ", " --help
Print a help message

.PP
With signing,
.BR --private-key ", " --certificate " and " --monotonic-count
are all mandatory.

.TP
.BI "-p\fR,\fB --private-key " private-key-file
Specify signer's private key file in PEM

.TP
.BI "-c\fR,\fB --certificate " certificate-file
Specify signer's certificate file in EFI certificate list format

.TP
.BI "-m\fR,\fB --monotonic-count " count
Specify a monotonic count which is set to be monotonically incremented
at every firmware update.

.TP
.B "-d\fR,\fB --dump_sig"
Dump signature data into *.p7 file

.SH "GUIDGEN OPTIONS"

.TP
.B "[GUID]"
The namespace/salt GUID, by default this is EFI_CAPSULE_NAMESPACE_GUID.
The format is:
    xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

.TP
.B DTB
The device tree blob file for the board.

.TP
.B IMAGE_NAME...
The names of the firmware images to generate GUIDs for.

.PP
.SH FILES
.TP
.I /EFI/UpdateCapsule
The directory in which all capsule files be placed

.SH SEE ALSO
.BR mkimage (1)

.SH AUTHORS
Written by AKASHI Takahiro <takahiro.akashi@linaro.org>

.SH HOMEPAGE
http://www.u-boot.org/