From patchwork Thu Jun 9 12:30:03 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Sughosh Ganu X-Patchwork-Id: 580309 Delivered-To: patch@linaro.org Received: by 2002:a05:7000:5806:0:0:0:0 with SMTP id j6csp735805max; Thu, 9 Jun 2022 05:34:13 -0700 (PDT) X-Google-Smtp-Source: ABdhPJx8MvHHKIu9+f9DpkZz4exoy1SpOeRQL13KTg+7EChbh1YPEnbsq8RfmfcOH1xRGjCVcY5H X-Received: by 2002:a92:cd8b:0:b0:2d4:74b0:f1b4 with SMTP id r11-20020a92cd8b000000b002d474b0f1b4mr16607758ilb.108.1654778053355; Thu, 09 Jun 2022 05:34:13 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1654778053; cv=none; d=google.com; s=arc-20160816; b=EtkvOBbnvGHsd2JSbF3z92Yle0BA0OtI82ijxxYGQt5MEBiQenwswidijifbNcsjoE dQ2F9B/Xu5v/t2t1hJpjJ3waShJrDpvBzMq4AoyQHggSZCkiSCtf7WM3pTRhaSfW783H MTcApkOz9xPURjO16H3Uud1cN4onwf6O3/WJqOy8F9UHvESkZQDQDq6tZdvb/yCcxYqy NUMKi8jUsHkRuUXxhfEA0QX/X8LtBN/HZaWLHehkVWX4LmgdteAxVv6O3SZ6iVO1VuwI Oq9V0gRD+tlIxLG2iBwLaN9nGLCOyVBZB4Yvb3sdAOzVIG8LlREWe2rVUkZ31sWVbtCg 6ysA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:content-transfer-encoding :mime-version:references:in-reply-to:message-id:date:subject:cc:to :from; bh=hewhq1F5+5j4u2bfyw4hgx1bvQOTkSfU4BHd3MKRl7c=; b=HGWAlLHnGj8OFjuOROroInhIQnRQYODoAVPQQs/3KVDHr3dg2Ht21Ss+xr2tSqPODh wwGMCKcfZWTBkaA709nkFBo5AQIcxys8ZW0uYz5cqSyTC/L6z+LVxtFUviEI2gi3iRWM v63O01rUygMiSwc+01V6ee6yuolzsP9DJA4jIedOCg1Y+iXiYpoOqGsxhUNMgK6Phfa7 viAlGRgaVykh0ZTxuNX9yYkMXex7+4iaRPvMxfrX13wGh3HqwOmT/AAlpD0NykCMUcUq YaBIRyjRGDxWyPT+tEZZ3EVd6pX66zRSRSasoi6gzlssgmqD6j4pPUxbxEp3KujetcC6 6k+Q== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from phobos.denx.de (phobos.denx.de. [85.214.62.61]) by mx.google.com with ESMTPS id s6-20020a056e0218c600b002d3f7e15037si26791517ilu.84.2022.06.09.05.34.12 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 09 Jun 2022 05:34:13 -0700 (PDT) Received-SPF: pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) client-ip=85.214.62.61; Authentication-Results: mx.google.com; spf=pass (google.com: domain of u-boot-bounces@lists.denx.de designates 85.214.62.61 as permitted sender) smtp.mailfrom=u-boot-bounces@lists.denx.de; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id B509384411; Thu, 9 Jun 2022 14:32:32 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Received: by phobos.denx.de (Postfix, from userid 109) id 326C9843EB; Thu, 9 Jun 2022 14:32:21 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-1.2 required=5.0 tests=BAYES_00,SPF_HELO_NONE, SPF_SOFTFAIL,T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.2 Received: from foss.arm.com (foss.arm.com [217.140.110.172]) by phobos.denx.de (Postfix) with ESMTP id C4DD7843F7 for ; Thu, 9 Jun 2022 14:31:49 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: phobos.denx.de; spf=fail smtp.mailfrom=sughosh.ganu@linaro.org Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.121.207.14]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 5017012FC; Thu, 9 Jun 2022 05:31:49 -0700 (PDT) Received: from a076522.blr.arm.com (a076522.blr.arm.com [10.162.16.44]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id 699AC3F93E; Thu, 9 Jun 2022 05:31:44 -0700 (PDT) From: Sughosh Ganu To: u-boot@lists.denx.de Cc: Heinrich Schuchardt , Ilias Apalodimas , Takahiro Akashi , Patrick Delaunay , Patrice Chotard , Simon Glass , Bin Meng , Tom Rini , Etienne Carriere , Michal Simek , Jassi Brar , Masami Hiramatsu , Sughosh Ganu Subject: [PATCH v5 16/23] FWU: doc: Update documentation for the FWU non-GPT MTD Date: Thu, 9 Jun 2022 18:00:03 +0530 Message-Id: <20220609123010.1017463-17-sughosh.ganu@linaro.org> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220609123010.1017463-1-sughosh.ganu@linaro.org> References: <20220609123010.1017463-1-sughosh.ganu@linaro.org> MIME-Version: 1.0 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.5 at phobos.denx.de X-Virus-Status: Clean From: Masami Hiramatsu Update documentation for the FWU non-GPT MTD device and mkfwumdata command. Signed-off-by: Masami Hiramatsu Signed-off-by: Sughosh Ganu --- doc/develop/uefi/fwu_updates.rst | 82 +++++++++++++++++++++++++++----- 1 file changed, 70 insertions(+), 12 deletions(-) diff --git a/doc/develop/uefi/fwu_updates.rst b/doc/develop/uefi/fwu_updates.rst index 1c34beb7d5..1ea54328d1 100644 --- a/doc/develop/uefi/fwu_updates.rst +++ b/doc/develop/uefi/fwu_updates.rst @@ -15,10 +15,11 @@ 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 +called FWU 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. +media. If the firmware images are stored on the flash device which +has no GPT, the platform driver can provide the image identification +feature. 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 @@ -43,21 +44,31 @@ The feature can be enabled by specifying the following configs:: CONFIG_FWU_MULTI_BANK_UPDATE=y CONFIG_CMD_FWU_METADATA=y CONFIG_DM_FWU_MDATA=y - CONFIG_FWU_MDATA_GPT_BLK=y CONFIG_FWU_NUM_BANKS= CONFIG_FWU_NUM_IMAGES_PER_BANK= + CONFIG_TOOLS_MKFWUMDATA=y + + CONFIG_FWU_MDATA_GPT_BLK=y + CONFIG_FWU_MDATA_SF=y -in the .config file +in the .config file. The first group of configs 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. +Update functionality. And the third group of configs are FWU Metadata +drivers. You can enable either one of ``CONFIG_FWU_MDATA_GPT_BLK`` and +``CONFIG_FWU_MDATA_SF`` or both of them, according to the platform +support. Anyway, a correct driver will be probed by devicetree node. + +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 ------------------------------------------------- +If your platform stores the firmware on GPT partitioned storage +device (e.g. eMMC/SD), please follow this section. + Before enabling the functionality in U-Boot, certain changes are required to be done on the storage device. Assuming a GPT partitioned storage device, the storage media needs to be partitioned with the @@ -74,7 +85,14 @@ media can have additional partitions of non-updatable images, like the EFI System Partition(ESP), a partition for the root file system etc. When generating the partitions, a few aspects need to be taken care -of. Each GPT partition entry in the GPT header has two GUIDs:: +of. The GPT itself has one GUID:: + + *DiskGUID* + +This DiskGUID value should correspond to the *location_uuid* field +of the FWU metadata. + +And each GPT partition entry in the GPT header has two GUIDs:: *PartitionTypeGUID* *UniquePartitionGUID* @@ -93,9 +111,49 @@ Similarly, the FWU specifications 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. +Setting up the device for non-GPT partitioned MTD device +-------------------------------------------------------- + +If your platform stores the firmware on non-GPT partitioned MTD +device, please follow this section. + +Before enabling the functionality in U-Boot, please confirm that +your platform correctly define (or generate) `dfu_alt_info`, which +has to have all *banks* as the dfu entries. Also, the devicetree's +`fwu_mdata` node must be "u-boot,fwu-mdata-mtd" compatible node +and has FWU metadata offsets on `mdata-offsets` property. +Please refer to U-Boot +`doc `__ for +the device tree bindings. + +Similar to the GPT, you can also define the DiskGUID, and the +UniquePartitionGUID in the devicetree as additional properties of +the "fixed-partitions" compatible partition nodes, and the platform +code can generate the `dfu_alt_info` from that. In this case, +*image_type_uuid* field of the FWU mdata is used instead of the +PartitionTypeGUID. + +Generate the FWU metadata image +------------------------------- + +To generate the FWU metadata raw image, you can use `tools/mkfwumdata` +command. + + tools/mkfwumdata -i <#images> -b <#banks> \ + \ + [location_uuid1,image_type_uuid1,image_uuid1_0,image_uuid1_1,...] \ + + +Or, if you know GUID instead of UUID, you can use --guid option. + + tools/mkfwumdata -i <#images> -b <#banks> --guid \ + \ + [DiskGUID1,PartitionTypeGUID1,UniquePartitionGUID1_0,UniquePartitionGUID1_1,...] \ + + +When generating the metadata, the *location_uuid*, the *image_type_uuid* +and the *image_uuid* values should match the *DiskGUID*, the +*PartitionTypeGUID* and the *UniquePartitionGUID* values respectively. Performing the Update ---------------------