From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 8644DC433FE for ; Tue, 4 Oct 2022 02:54:49 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 2158D84BB9; Tue, 4 Oct 2022 04:54:47 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.b="yduVvoNk"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id BEB6784BDB; Tue, 4 Oct 2022 04:54:45 +0200 (CEST) Received: from mail-pl1-x629.google.com (mail-pl1-x629.google.com [IPv6:2607:f8b0:4864:20::629]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9F94084B70 for ; Tue, 4 Oct 2022 04:54:41 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=takahiro.akashi@linaro.org Received: by mail-pl1-x629.google.com with SMTP id h10so8739505plb.2 for ; Mon, 03 Oct 2022 19:54:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date:from:to:cc :subject:date:message-id:reply-to; bh=mZFEG1EwAARLSrvKTd7D4l9Z7GY2FkHf3Jp1yURSXTk=; b=yduVvoNkDiJkgw+uC03a8qhRJ5aGVA6/MOHXTB/zJxqR4sOGxymEp+EIRPYabpfV5x IMvEJASwR1ZuDX/a6SZAyljG4j81GohSu5Ap6+7Rr3wI5g4OskHZSwZGtD27Y/znAcYV wemNPywuia/f5mdLZt0x4Yl4F85Gi4WGNg04vmwMAe23O6+u1T99sIXsEQH+g6S78MJu MegNv4g3AD2HtHhSyksvlx6Ohiyv8gHey3egwMk1fV87usj2D9bZGDrlEx6N2uA9kveu HkI1DXYH+V2dwFHYRrQTh2vOYwJ2Ss1sGf7K7DSkWqRwajzblN9LCnfb+6Nfo/PgE5/S Ym8w== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=in-reply-to:content-disposition:mime-version:references :mail-followup-to:message-id:subject:cc:to:from:date :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=mZFEG1EwAARLSrvKTd7D4l9Z7GY2FkHf3Jp1yURSXTk=; b=oS/1Izrohv+Xg5J5PcZW9UyrCWaCVAKB3E8N21CKsQNZvAr8D99kgDjPlF3gJVma/u sl/PS85p19RZeph7F5hVyvhOJ7xWscaTOCSyPaH7Lw4Kkm9eEyzwhkjLQFlw8NMrmUBr 448Y267j0KD/kTclRNckRHfP9mm2RQb1gtXm9sjYvtTb/calsvwX1Nr9HpSvlP8+7V3f O2ZYvN6vTr1f4gCE6yKsjdIkJ2ivVCaMWCTkofympYxHR4d7LuTeopwefhlPSqDi1Tmb qxE0sQsXK8tPscy2z9FSjqXGOjcCJk38DLKBasILrGKMJ/n3iVMk/f3Rkm5rbwsEAhhg PYRg== X-Gm-Message-State: ACrzQf0LXCVapcZzlL9aqHjl3+lIxoXt3gzoQO0dGLsmd/TSu+5L3yfB f64ivL8k/XbCo8rnTrNrNyWEcA== X-Google-Smtp-Source: AMsMyM4Qjo4zPdOqc1+62Lw3r0b5ql/nN9YsD+SPwdv/A70vXXla4uiuw1AkHM8MG/iyyJCYxCtMpQ== X-Received: by 2002:a17:90a:1742:b0:20a:8f40:9b8a with SMTP id 2-20020a17090a174200b0020a8f409b8amr10565108pjm.151.1664852079787; Mon, 03 Oct 2022 19:54:39 -0700 (PDT) Received: from laputa ([2400:4050:c3e1:100:5205:befa:c3e8:6c20]) by smtp.gmail.com with ESMTPSA id j23-20020a63cf17000000b0041cd5ddde6fsm7345438pgg.76.2022.10.03.19.54.35 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 03 Oct 2022 19:54:38 -0700 (PDT) Date: Tue, 4 Oct 2022 11:54:33 +0900 From: Takahiro Akashi To: Sughosh Ganu Cc: u-boot@lists.denx.de, Heinrich Schuchardt , Ilias Apalodimas , Patrick Delaunay , Patrice Chotard , Simon Glass , Bin Meng , Tom Rini , Etienne Carriere , Michal Simek , Jassi Brar Subject: Re: [PATCH v11 15/15] FWU: doc: Add documentation for the FWU feature Message-ID: <20221004025433.GB36861@laputa> Mail-Followup-To: Takahiro Akashi , Sughosh Ganu , u-boot@lists.denx.de, Heinrich Schuchardt , Ilias Apalodimas , Patrick Delaunay , Patrice Chotard , Simon Glass , Bin Meng , Tom Rini , Etienne Carriere , Michal Simek , Jassi Brar References: <20220928092956.2535777-1-sughosh.ganu@linaro.org> <20220928092956.2535777-16-sughosh.ganu@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20220928092956.2535777-16-sughosh.ganu@linaro.org> X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean Sughosh, On Wed, Sep 28, 2022 at 02:59:56PM +0530, Sughosh Ganu wrote: > Add documentation for the FWU Multi Bank Update feature. The document > describes the steps needed for setting up the platform for the > feature, as well as steps for enabling the feature on the platform. > > Signed-off-by: Sughosh Ganu > --- > Changes since V10: > * Fix review comments suggested by Etienne > * Add a paragraph in the capsule update section to highlight the > difference in ImageIndex correlation with DFU alt num with FWU feature > enabled > > doc/develop/uefi/fwu_updates.rst | 173 +++++++++++++++++++++++++++++++ > doc/develop/uefi/index.rst | 1 + > doc/develop/uefi/uefi.rst | 10 ++ > 3 files changed, 184 insertions(+) > create mode 100644 doc/develop/uefi/fwu_updates.rst > > diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst > new file mode 100644 > index 0000000000..292feceb9a > --- /dev/null > +++ b/doc/develop/uefi/fwu_updates.rst > @@ -0,0 +1,173 @@ > +.. SPDX-License-Identifier: GPL-2.0+ > +.. Copyright (c) 2022 Linaro Limited > + > +FWU Multi Bank Updates in U-Boot > +================================ > + > +The FWU Multi Bank Update feature implements the firmware update > +mechanism described in the PSA Firmware Update for A-profile Arm > +Architecture specification [1]. Certain aspects of the Dependable > +Boot specification [2] are also implemented. The feature provides a > +mechanism to have multiple banks of updatable firmware images and for > +updating the firmware images on the non-booted bank. On a successful > +update, the platform boots from the updated bank on subsequent > +boot. The UEFI capsule-on-disk update feature is used for performing > +the actual updates of the updatable firmware images. > + > +The bookkeeping of the updatable images is done through a structure > +called metadata. Currently, the FWU metadata supports identification > +of images based on image GUIDs stored on a GPT partitioned storage > +media. There are plans to extend the metadata structure for non GPT > +partitioned devices as well. > + > +Accessing the FWU metadata is done through generic API's which are > +defined in a driver which complies with the U-Boot's driver model. A > +new uclass UCLASS_FWU_MDATA has been added for accessing the FWU > +metadata. Individual drivers can be added based on the type of storage > +media, and its partitioning method. Details of the storage device > +containing the FWU metadata partitions are specified through a U-Boot > +specific device tree property `fwu-mdata-store`. Please refer to > +U-Boot `doc `__ > +for the device tree bindings. > + > +Enabling the FWU Multi Bank Update feature > +------------------------------------------ > + > +The feature can be enabled by specifying the following configs:: > + > + CONFIG_EFI_CAPSULE_ON_DISK=y > + CONFIG_EFI_CAPSULE_FIRMWARE_MANAGEMENT=y > + CONFIG_EFI_CAPSULE_FIRMWARE_RAW=y > + > + CONFIG_FWU_MULTI_BANK_UPDATE=y > + CONFIG_CMD_FWU_METADATA=y > + CONFIG_FWU_MDATA=y > + CONFIG_FWU_MDATA_GPT_BLK=y > + CONFIG_FWU_NUM_BANKS= > + CONFIG_FWU_NUM_IMAGES_PER_BANK= > + > +in the .config file > + > +The first group of configuration settings enable the UEFI > +capsule-on-disk update functionality. The second group of configs > +enable the FWU Multi Bank Update functionality. Please refer to the > +section :ref:`uefi_capsule_update_ref` for more details on generation > +of the UEFI capsule. > + > +Setting up the device for GPT partitioned storage > +------------------------------------------------- > + > +Before enabling the functionality in U-Boot, a GPT partitioned storage > +device is required. Assuming a GPT partitioned storage device, the > +storage media needs to be partitioned with the correct number of > +partitions, given the number of banks and number of images per bank > +that the platform is going to support. Each updatable firmware image > +will be stored on a separate partition. In addition, the two copies > +of the FWU metadata will be stored on two separate partitions. > + > +As an example, a platform supporting two banks with each bank > +containing three images would need to have 2 * 3 = 6 partitions plus > +the two metadata partitions, or 8 partitions. In addition the storage > +media can have additional partitions of non-updatable images, like the > +EFI System Partition(ESP), a partition for the root file system > +etc. An example list of images on the storage medium would be > + > +* FWU metadata 1 > +* U-Boot 1 > +* OP-TEE 1 > +* FWU metadata 2 > +* OP-TEE 2 > +* U-Boot 2 > +* ESP > +* rootfs > + > +When generating the partitions, a few aspects need to be taken care > +of. Each GPT partition entry in the GPT header has two GUIDs:: > + > +* PartitionTypeGUID > +* UniquePartitionGUID > + > +The PartitionTypeGUID value should correspond to the > +``image_type_uuid`` field of the FWU metadata. This field is used to > +identify a given type of updatable firmware image, e.g. U-Boot, > +OP-TEE, FIP etc. This GUID should also be used for specifying the > +`--guid` parameter when generating the capsule. > + > +The UniquePartitionGUID value should correspond to the ``image_uuid`` > +field in the FWU metadata. This GUID is used to identify images of a > +given image type in different banks. Well, what is not clear to me here is: - who is responsible to set up FWU metadata and when - how FWU metadata is related to fw_images and update_info which are used in normal case, which is mentioned in develop/uefi/uefi.rst I know the whole text here is dedicated to A/B update, but I think it would also be helpful to have a single document which covers both cases for developers to understand how differently FWU is configured for those cases. -Takahiro Akashi > + > +Similarly, the FWU specification defines the GUID value to be used > +for the metadata partitions. This would be the PartitionTypeGUID for > +the metadata partitions. > + > +When generating the metadata, the ``image_type_uuid`` and the > +``image_uuid`` values should match the *PartitionTypeGUID* and the > +*UniquePartitionGUID* values respectively. > + > +Performing the Update > +--------------------- > + > +Once the storage media has been partitioned and populated with the > +metadata partitions, the UEFI capsule-on-disk update functionality can > +be used for performing the update. Refer to the section > +:ref:`uefi_capsule_update_ref` for details on how the update can be > +invoked. > + > +On a successful update, the FWU metadata gets updated to reflect the > +bank from which the platform would be booting on subsequent boot. > + > +Based on the value of bit15 of the Flags member of the capsule header, > +the updated images would either be accepted by the U-Boot's UEFI > +implementation, or by the Operating System. If the Operating System is > +accepting the firmware images, it does so by generating an empty > +*accept* capsule. The Operating System can also reject the updated > +firmware by generating a *revert* capsule. The empty capsule can be > +applied by using the exact same procedure used for performing the > +capsule-on-disk update. > + > +The task of accepting the different firmware images, post an update > +may be done by multiple, separate components in the Operating > +System. To help identify the firmware image that is being accepted, > +the accept capsule passes the image GUID of the firmware image being > +accepted. The relevant code in U-Boot then sets the Accept bit of the > +corresponding firmware image for which the accept capsule was > +found. Only when all the firmware components in a bank have been > +accepted does the platform transition from trial state to regular > +state. > + > +The revert capsule on the other hand does not pass any image GUID, > +since reverting any image of the bank has the same result of the > +platform booting from the other bank on subsequent boot. > + > +Generating an empty capsule > +--------------------------- > + > +The empty capsule can be generated using the mkeficapsule utility. To > +build the tool, enable:: > + > + CONFIG_TOOLS_MKEFICAPSULE=y > + > +Run the following commands to generate the accept/revert capsules:: > + > +.. code-block:: bash > + > + $ ./tools/mkeficapsule \ > + [--fw-accept --guid ] | \ > + [--fw-revert] \ > + > + > +Some examples of using the mkeficapsule tool for generation of the > +empty capsule would be:: > + > +.. code-block:: bash > + > + $ ./tools/mkeficapsule --fw-accept --guid \ > + > + $ ./tools/mkeficapsule --fw-revert > + > +Links > +----- > + > +* [1] https://developer.arm.com/documentation/den0118/a/ - FWU Specification > +* [2] https://git.codelinaro.org/linaro/dependable-boot/mbfw/uploads/6f7ddfe3be24e18d4319e108a758d02e/mbfw.pdf - Dependable Boot Specification > diff --git a/doc/develop/uefi/index.rst b/doc/develop/uefi/index.rst > index 7e65dbc5d5..e26b1fbe05 100644 > --- a/doc/develop/uefi/index.rst > +++ b/doc/develop/uefi/index.rst > @@ -13,3 +13,4 @@ can be run an UEFI payload. > uefi.rst > u-boot_on_efi.rst > iscsi.rst > + fwu_updates.rst > diff --git a/doc/develop/uefi/uefi.rst b/doc/develop/uefi/uefi.rst > index 941e427093..b5c83db65a 100644 > --- a/doc/develop/uefi/uefi.rst > +++ b/doc/develop/uefi/uefi.rst > @@ -277,6 +277,8 @@ Enable ``CONFIG_OPTEE``, ``CONFIG_CMD_OPTEE_RPMB`` and ``CONFIG_EFI_MM_COMM_TEE` > > [1] https://optee.readthedocs.io/en/latest/building/efi_vars/stmm.html > > +.. _uefi_capsule_update_ref: > + > Enabling UEFI Capsule Update feature > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > @@ -377,6 +379,14 @@ following command:: > > dfu list > > +When the FWU Multi Bank Update feature is enabled on the platform, the > +image index is used only to identify the image index with the image > +GUID. The image index would not correspond to the dfu alt number. This > +is because the FWU feature supports multiple partitions(banks) of > +updatable images, and the actual dfu alt number to which the image is > +to be written to is determined at runtime, based on the value of the > +update bank to which the image is to be written. > + > When using the FMP for FIT images, the image index value needs to be > set to 1. > > -- > 2.34.1 >