[PATCH 3/3] doc: Update CapsuleUpdate READMEs

[AKASHI Takahiro]

On Fri, Jul 16, 2021 at 10:09:40AM +0300, Ilias Apalodimas wrote:
> > > +
> > > +The directory \EFI\UpdateCapsule is checked for capsules only within the
> > > +EFI system partition on the device specified in the active boot option
> > > +determine by reference to BootNext variable or BootOrder variable processing.
> > 
> > %s/determine/determined/
> > 
> 
> sure 
> 
> > > +The active Boot Variable is the variable with highest priority BootNext or
> > 
> > Does only the device have to be present or also the file?
> > Should we check only the binary or also the initrd?
> 
> I don't follow on the initrd.
> The whole paragraph is copied verbatim from the EFI spec. Basically you
> need a valid boot option (with priority) that points to the ESP partition
> your capsule is.  Akashi's code is also doing the right thing following the
> spec.

I *guess* that Heinrich thinks of all the device paths
contained in an boot option, including "initrd" that
you added a support for.
IIRC, all the paths in one option must point to the same device.
(So no for Heinrich's concern?)

-Takahiro Akashi

> Regards
> /Ilias
> > 
> > Best regards
> > 
> > Heinrich
> > 
> > > +within BootOrder that refers to a device found to be present. Boot variables
> > > +in BootOrder but referring to devices not present are ignored when determining
> > > +active boot variable.
> > > +Before starting a capsule update make sure your capsules are installed in the
> > > +correct ESP partition or set BootNext.
> > > +
> > > +Performing the update
> > > +*********************
> > > +
> > > +Since U-boot doesn't currently support SetVariable at runtime there's a Kconfig
> > > +option (CONFIG_EFI_IGNORE_OSINDICATIONS) to disable the OsIndications variable
> > > +check. If that option is enabled just copy your capsule to \EFI\UpdateCapsule.
> > > +
> > > +If that option is disabled, you'll need to set the OsIndications variable with::
> > > +
> > > +    => setenv -e -nv -bs -rt -v OsIndications =0x04
> > > +
> > > +Finally, the capsule update can be initiated either by rebooting the board,
> > > +which is the preferred method, or by issuing the following command::
> > > +
> > > +    => efidebug capsule disk-update
> > > +
> > > +**The efidebug command is should only be used during debugging/development.**
> > > +
> > > +Enabling Capsule Authentication
> > > +*******************************
> > > +
> > > +The UEFI specification defines a way of authenticating the capsule to
> > > +be updated by verifying the capsule signature. The capsule signature
> > > +is computed and prepended to the capsule payload at the time of
> > > +capsule generation. This signature is then verified by using the
> > > +public key stored as part of the X509 certificate. This certificate is
> > > +in the form of an efi signature list (esl) file, which is embedded as
> > > +part of U-Boot.
> > > +
> > > +The capsule authentication feature can be enabled through the
> > > +following config, in addition to the configs listed above for capsule
> > > +update::
> > > +
> > > +    CONFIG_EFI_CAPSULE_AUTHENTICATE=y
> > > +    CONFIG_EFI_CAPSULE_KEY_PATH=<path to .esl cert>
> > > +
> > > +The public and private keys used for the signing process are generated
> > > +and used by the steps highlighted below::
> > > +
> > > +    1. Install utility commands on your host
> > > +       * OPENSSL
> > > +       * efitools
> > > +
> > > +    2. Create signing keys and certificate files on your host
> > > +
> > > +        $ openssl req -x509 -sha256 -newkey rsa:2048 -subj /CN=CRT/ \
> > > +            -keyout CRT.key -out CRT.crt -nodes -days 365
> > > +        $ cert-to-efi-sig-list CRT.crt CRT.esl
> > > +
> > > +        $ openssl x509 -in CRT.crt -out CRT.cer -outform DER
> > > +        $ openssl x509 -inform DER -in CRT.cer -outform PEM -out CRT.pub.pem
> > > +
> > > +        $ openssl pkcs12 -export -out CRT.pfx -inkey CRT.key -in CRT.crt
> > > +        $ openssl pkcs12 -in CRT.pfx -nodes -out CRT.pem
> > > +
> > > +The capsule file can be generated by using the GenerateCapsule.py
> > > +script in EDKII::
> > > +
> > > +    $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \
> > > +      <capsule_file_name> --monotonic-count <val> --fw-version \
> > > +      <val> --lsv <val> --guid \
> > > +      e2bb9c06-70e9-4b14-97a3-5a7913176e3f --verbose \
> > > +      --update-image-index <val> --signer-private-cert \
> > > +      /path/to/CRT.pem --trusted-public-cert \
> > > +      /path/to/CRT.pub.pem --other-public-cert /path/to/CRT.pub.pem \
> > > +      <u-boot.bin>
> > > +
> > > +Place the capsule generated in the above step on the EFI System
> > > +Partition under the EFI/UpdateCapsule directory
> > > +
> > > +Testing on QEMU
> > > +***************
> > > +
> > > +Currently, support has been added on the QEMU ARM64 virt platform for
> > > +updating the U-Boot binary as a raw image when the platform is booted
> > > +in non-secure mode, i.e. with CONFIG_TFABOOT disabled. For this
> > > +configuration, the QEMU platform needs to be booted with
> > > +'secure=off'. The U-Boot binary placed on the first bank of the NOR
> > > +flash at offset 0x0. The U-Boot environment is placed on the second
> > > +NOR flash bank at offset 0x4000000.
> > > +
> > > +The capsule update feature is enabled with the following configuration
> > > +settings::
> > > +
> > > +    CONFIG_MTD=y
> > > +    CONFIG_FLASH_CFI_MTD=y
> > > +    CONFIG_CMD_MTDPARTS=y
> > > +    CONFIG_CMD_DFU=y
> > > +    CONFIG_DFU_MTD=y
> > > +    CONFIG_PCI_INIT_R=y
> > > +    CONFIG_EFI_CAPSULE_ON_DISK=y
> > > +    CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y
> > > +    CONFIG_EFI_CAPSULE_FIRMWARE=y
> > > +    CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y
> > > +    CONFIG_EFI_CAPSULE_FMP_HEADER=y
> > > +
> > > +In addition, the following config needs to be disabled(QEMU ARM specific)::
> > > +
> > > +    CONFIG_TFABOOT
> > > +
> > > +The capsule file can be generated by using the tools/mkeficapsule::
> > > +
> > > +    $ mkeficapsule --raw <u-boot.bin> --index 1 <capsule_file_name>
> > > +
> > >   Executing the boot manager
> > >   ~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > 
> > > 
> >