[PATCH 8/8] qemu: arm64: Add documentation for capsule update

[Sughosh Ganu]

Add documentation highlighting the steps for using the uefi capsule
update feature for updating the u-boot firmware image.

Signed-off-by: Sughosh Ganu <sughosh.ganu at linaro.org>
---
 doc/board/emulation/qemu-arm.rst | 112 +++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)

diff --git a/doc/board/emulation/qemu-arm.rst b/doc/board/emulation/qemu-arm.rst
index ca751d4af4..8649d593ed 100644
--- a/doc/board/emulation/qemu-arm.rst
+++ b/doc/board/emulation/qemu-arm.rst
@@ -80,3 +80,115 @@ can be enabled with the following command line parameters:
     -drive if=none,file=disk.img,id=mydisk -device nvme,drive=mydisk,serial=foo
 
 These have been tested in QEMU 2.9.0 but should work in at least 2.5.0 as well.
+
+Enabling Uefi Capsule Update feature
+------------------------------------
+
+Support has been added for the uefi capsule update feature which
+enables updating the u-boot image using the uefi firmware management
+protocol (fmp). The capsules are not passed to the firmware through
+the UpdateCapsule runtime service. Instead, capsule-on-disk
+functionality is used for fetching the capsule from the EFI System
+Partition (ESP). Currently, support has been added for the arm64
+target booting with arm trusted firmware. The This feature is enabled
+with the following configs::
+
+    CONFIG_EFI_CAPSULE_ON_DISK=y
+    CONFIG_EFI_FIRMWARE_MANAGEMENT_PROTOCOL=y
+    CONFIG_CMD_EFIDEBUG=y
+
+The capsule file can be generated by using the GenerateCapsule.py
+script in edk2::
+
+    $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \
+    <capsule_file_name> --fw-version <val> --lsv <val> --guid \
+    fb90808a-ba9a-4d42-b9a2-a7a937144aee --verbose --update-image-index \
+    <val> --verbose <u-boot.bin>
+
+
+As per the uefi specification, the capsule file needs to be placed on
+the EFI System Partition, under the EFI/UpdateCapsule/ directory. The
+EFI System Partition can be a virtio-blk-device.
+
+Before initiating the firmware update, the efi variables BootNext and
+BootXXXX need to be set. The BootXXXX variable needs to be pointing to
+the EFI System Partition which contains the capsule file. The
+BootNext and BootXXXX variables can be set using the efidebug
+command::
+
+    => efidebug boot add 0 Boot0000 virtio 0:1 <capsule_file_name>
+    => efidebug boot next 0
+
+The OsIndications efi variable needs to be set with the
+EFI_OS_INDICATIONS_FILE_CAPSULE_DELIVERY_SUPPORTED flag set::
+
+    => setenv -e -nv -bs -rt OsIndications =0x04
+    => saveenv
+
+The capsule update function will be invoked on subsequent boot as part
+of the main_loop function. The updated u-boot image will be booted on
+subsequent boot.
+
+
+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 stored as an
+efi variable.
+
+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
+
+The esl file can be generated as follows:
+
+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
+
+3. Store the esl file generated above as an efi variable::
+
+        => fatload virtio 0:1 <load_addr> EFI/CRT.esl
+        => setenv -e -nv -bs -rt -i <load_addr>,$filesize CRT
+
+        => setenv capsule_authentication_enabled 1
+        => setenv -e -nv -bs -rt OsIndication =0x04
+        => saveenv
+
+Setting the environment variable capsule_authentication_enabled
+enables the capsule authentication.
+
+4. The capsule file can be generated by using the GenerateCapsule.py
+   script in edk2::
+
+        $ ./BaseTools/BinWrappers/PosixLike/GenerateCapsule -e -o \
+	<capsule_file_name> --monotonic-count <val> --fw-version \
+	<val> --lsv <val> --guid \
+	fb90808a-ba9a-4d42-b9a2-a7a937144aee --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>
+
+Once the capsule has been generated, use the same instructions as
+mentioned above for placing the capsule on the EFI System Partition
+and subsequently to initiate the update.
-- 
2.17.1