From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM02-SN1-obe.outbound.protection.outlook.com (NAM02-SN1-obe.outbound.protection.outlook.com [40.92.5.67]) by mx.groups.io with SMTP id smtpd.web12.8966.1603152026677065717 for ; Mon, 19 Oct 2020 17:00:26 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@outlook.com header.s=selector1 header.b=U1XK5rPT; spf=pass (domain: outlook.com, ip: 40.92.5.67, mailfrom: michael.kubacki@outlook.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=dcyig8CYe9TpsXnnNoxlsT/jVVrRfn1H54s/SHNoq+KQwlMWKmHcCSxjQXYs4+PqYYtp+gMTURiopUyV5NsdzxtQtB/0k7i+Ws+tJ1cns+LZOb4E5L5ZyuADOOgNNSFIsn+26NQdzwTJfqnY4M9g0RTPBPxVp0JdWaAkDK2lkq5DGCkq/ZK5PTaXiGd9YeVEfGtZwja1i1p3DjY8Iyodp2SNby2yWq6+/L0EuNDcgzFIMXQc0b+hK46hGfTHvoZ5aJcS5UWPtxEW7VE218je6/wX7GtFSWvF0fJXnAAA0AtnrxLiGecfpLDUKcScPWtzchUVoifRd8fGN4BAkrnoZQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=oyQLt0yrGVubQorC6NPqc56xyXvSC/FYf131BUCYVqc=; b=g1zg64pd5Uv6hrlIr3qY+NhnxHtpSQvoIfMryDbQJUKb5FShI0qL0a3czx80A1y8o6I6sRR4KviDIzfbupKwcaiJdeKc55hBd38G2vc+IP/qiHJCZWPCEjFyhHqPWTzqHo2i2yENVmP0TNtodoGB7hK5RilVq2MDwtoDnyQAxh6I9k+xL4Kv+18PQVUNp8BtRlEiymIPsAAhikrnYpU7pSglLhSOPOQJfnmLfyIsNRrRiUNDuan9n/Ask9xu+3oxoKZC9llS1LZzqzUxBN9wLe0TbxYJmEEiZ7doCzYHWJXWC3yV3/4Yx031aO3YZMHHI9tzkOYUxJfMUng9bcoYXQ== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=oyQLt0yrGVubQorC6NPqc56xyXvSC/FYf131BUCYVqc=; b=U1XK5rPTDh/5givbANiWOKwFeAlwya3ehXJOHC2PY4GPUMvVMfRwIY2X9G72G/JCeAxh7GvenYm5wZtQQ+UZT+K8T7V9rpkicFoz5p0Zpa9RKs8YeyfmBrvdw1dXkYmTJByNXLl/j6olr/7KyXdi5spDVG9yovzaazEJcnQz5qUIYDxwU6vJI097uAesWtWd+QMtuf+gKGBgYZg2jCoDaGWtC56xs7Dr140AVgR2BeIoYYjeigQwJJ24z4qj2+I0hdBgmy3244XfbOM1bXj2bJIZSjDTKI227tiwl51xijks817fT5qKsJidj0oexwmoTJ22pnh6SoYdLD1EnwWiQA== Received: from CY1NAM02FT029.eop-nam02.prod.protection.outlook.com (10.152.74.57) by CY1NAM02HT078.eop-nam02.prod.protection.outlook.com (10.152.74.137) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3477.23; Tue, 20 Oct 2020 00:00:23 +0000 Received: from MWHPR07MB3440.namprd07.prod.outlook.com (2a01:111:e400:7e45::4e) by CY1NAM02FT029.mail.protection.outlook.com (2a01:111:e400:7e45::399) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3477.21 via Frontend Transport; Tue, 20 Oct 2020 00:00:23 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:335C60C9775DB839AA14E2679224BBF4E3AD00C9129E57308CA2BE5805CD7BC1;UpperCasedChecksum:3FB283D5A3EF8AFE7D8F4992B26334DAD3C929A2597C46D0E6F508E82E76E024;SizeAsReceived:7680;Count:47 Received: from MWHPR07MB3440.namprd07.prod.outlook.com ([fe80::858f:bd50:1b65:e803]) by MWHPR07MB3440.namprd07.prod.outlook.com ([fe80::858f:bd50:1b65:e803%7]) with mapi id 15.20.3477.028; Tue, 20 Oct 2020 00:00:23 +0000 From: "Michael Kubacki" To: devel@edk2.groups.io CC: Liming Gao , Michael D Kinney , Guomin Jiang , Wei6 Xu Subject: [PATCH v6 6/6] FmpDevicePkg/FmpDeviceLib: Add Last Attempt Status to Check/Set API Date: Mon, 19 Oct 2020 16:59:39 -0700 Message-ID: X-Mailer: git-send-email 2.28.0.windows.1 In-Reply-To: <20201019235939.2320-1-michael.kubacki@outlook.com> References: <20201019235939.2320-1-michael.kubacki@outlook.com> X-TMN: [sMERK/j1mxXONbyVikITY6TivK6h9aCU4TEjW88hoSswY6DdFieHcRWv2gcRL+X9] X-ClientProxiedBy: MWHPR14CA0067.namprd14.prod.outlook.com (2603:10b6:300:81::29) To MWHPR07MB3440.namprd07.prod.outlook.com (2603:10b6:301:69::28) Return-Path: michael.kubacki@outlook.com X-Microsoft-Original-Message-ID: <20201019235939.2320-7-michael.kubacki@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from localhost.localdomain (2001:4898:80e8:2:819c:275:72be:ff50) by MWHPR14CA0067.namprd14.prod.outlook.com (2603:10b6:300:81::29) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3477.21 via Frontend Transport; Tue, 20 Oct 2020 00:00:20 +0000 X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 47 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: 43584682-d5eb-4b79-0387-08d8748b22ff X-MS-TrafficTypeDiagnostic: CY1NAM02HT078: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: QxcAoCUcngXccrfOIQiPRHEQDslnlUpRiDGTIyMSBvzEB34qGRj9xcuN7oL0lwKKg8cdznpTSdvt/MmZtJRp2EPz+P/HoM56bXCZepIqP9onUErRY0KK7cHPmGszx7nkFozi6vLzhLELWU9DRH3Z3dQadKKWifHeH2mSm8vooBzGLId4dj+v6Qx63AxAmJCcDR0Q0vYzPyzoWx4BEBOWRw== X-MS-Exchange-AntiSpam-MessageData: ZEDPvc15l8EcPVhAW04SoNtFvsxpTM5qO+FZyYLr+UCOUjosY3zveekRhwAxiVZJ2unYGLxeelcRdO+T74SbBBjv35dcnYN6ZDOSs/DV6tsa7RK1AVQ+2yXTVmYuTdSBGOlNMyUVeLjQxMQ4Kq6z1p7Hey+QzhDX4u6XfyYarQZDQr7HxFm0Dt6HA7rFwHh/QUL2LRTlx7bjcJp+fHaV3A== X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 43584682-d5eb-4b79-0387-08d8748b22ff X-MS-Exchange-CrossTenant-OriginalArrivalTime: 20 Oct 2020 00:00:21.1837 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-AuthSource: CY1NAM02FT029.eop-nam02.prod.protection.outlook.com X-MS-Exchange-CrossTenant-AuthAs: Anonymous X-MS-Exchange-CrossTenant-FromEntityHeader: Internet X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: CY1NAM02HT078 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain From: Michael Kubacki Provides the ability for a given FMP device library instance to return a Last Attempt Status code during check image and set image operations with FmpDeviceCheckImageEx() and FmpDeviceSetImageEx(). Cc: Liming Gao Cc: Michael D Kinney Cc: Guomin Jiang Cc: Wei6 Xu Signed-off-by: Michael Kubacki Acked-by: Liming Gao Reviewed-by: Wei6 Xu --- FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c | 144 +++++++++++++++= ++++- FmpDevicePkg/Include/Library/FmpDeviceLib.h | 121 +++++++++++++++= - 2 files changed, 263 insertions(+), 2 deletions(-) diff --git a/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c b/FmpDevi= cePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c index 316de12e910c..f4f57b29bdb1 100644 --- a/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c +++ b/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c @@ -2,7 +2,7 @@ Provides firmware device specific services to support updates of a firmw= are image stored in a firmware device. =20 - Copyright (c) 2016, Microsoft Corporation. All rights reserved.
+ Copyright (c) Microsoft Corporation.
Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.
=20 SPDX-License-Identifier: BSD-2-Clause-Patent @@ -10,6 +10,7 @@ **/ =20 #include +#include #include =20 /** @@ -407,6 +408,57 @@ FmpDeviceCheckImage ( OUT UINT32 *ImageUpdatable ) { + UINT32 LastAttemptStatus; + + return FmpDeviceCheckImageWithStatus (Image, ImageSize, ImageUpdatable, = &LastAttemptStatus); +} + +/** + Checks if a new firmware image is valid for the firmware device. This + function allows firmware update operation to validate the firmware image + before FmpDeviceSetImage() is called. + + @param[in] Image Points to a new firmware image. + @param[in] ImageSize Size, in bytes, of a new firmware image. + @param[out] ImageUpdatable Indicates if a new firmware image is val= id for + a firmware update to the firmware device= . The + following values from the Firmware Manag= ement + Protocol are supported: + IMAGE_UPDATABLE_VALID + IMAGE_UPDATABLE_INVALID + IMAGE_UPDATABLE_INVALID_TYPE + IMAGE_UPDATABLE_INVALID_OLD + IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE + @param[out] LastAttemptStatus A pointer to a UINT32 that holds the las= t attempt + status to report back to the ESRT table = in case + of error. This value will only be checke= d when this + function returns an error. + + The return status code must fall in the = range of + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_E= RROR_CODE_VALUE to + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_E= RROR_CODE_VALUE. + + If the value falls outside this range, i= t will be converted + to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFU= L. + + @retval EFI_SUCCESS The image was successfully checked. Addi= tional + status information is returned in + ImageUpdatable. + @retval EFI_INVALID_PARAMETER Image is NULL. + @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL. + +**/ +EFI_STATUS +EFIAPI +FmpDeviceCheckImageWithStatus ( + IN CONST VOID *Image, + IN UINTN ImageSize, + OUT UINT32 *ImageUpdatable, + OUT UINT32 *LastAttemptStatus + ) +{ + *LastAttemptStatus =3D LAST_ATTEMPT_STATUS_SUCCESS; + return EFI_SUCCESS; } =20 @@ -473,6 +525,96 @@ FmpDeviceSetImage ( OUT CHAR16 **AbortReason ) { + UINT32 LastAttemptStatus; + + return FmpDeviceSetImageWithStatus ( + Image, + ImageSize, + VendorCode, + Progress, + CapsuleFwVersion, + AbortReason, + &LastAttemptStatus + ); +} + +/** + Updates a firmware device with a new firmware image. This function retu= rns + EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware= image + is updatable, the function should perform the following minimal validati= ons + before proceeding to do the firmware image update. + - Validate that the image is a supported image for this firmware devic= e. + Return EFI_ABORTED if the image is not supported. Additional detail= s + on why the image is not a supported image may be returned in AbortRe= ason. + - Validate the data from VendorCode if is not NULL. Firmware image + validation must be performed before VendorCode data validation. + VendorCode data is ignored or considered invalid if image validation + fails. Return EFI_ABORTED if the VendorCode data is invalid. + + VendorCode enables vendor to implement vendor-specific firmware image up= date + policy. Null if the caller did not specify the policy or use the defaul= t + policy. As an example, vendor can implement a policy to allow an option= to + force a firmware image update when the abort reason is due to the new fi= rmware + image version is older than the current firmware image version or bad im= age + checksum. Sensitive operations such as those wiping the entire firmware= image + and render the device to be non-functional should be encoded in the imag= e + itself rather than passed with the VendorCode. AbortReason enables vend= or to + have the option to provide a more detailed description of the abort reas= on to + the caller. + + @param[in] Image Points to the new firmware image. + @param[in] ImageSize Size, in bytes, of the new firmware image. + @param[in] VendorCode This enables vendor to implement vendor-sp= ecific + firmware image update policy. NULL indica= tes + the caller did not specify the policy or u= se the + default policy. + @param[in] Progress A function used to report the progress of + updating the firmware device with the new + firmware image. + @param[in] CapsuleFwVersion The version of the new firmware image from= the + update capsule that provided the new firmw= are + image. + @param[out] AbortReason A pointer to a pointer to a Null-terminate= d + Unicode string providing more details on a= n + aborted operation. The buffer is allocated= by + this function with + EFI_BOOT_SERVICES.AllocatePool(). It is t= he + caller's responsibility to free this buffe= r with + EFI_BOOT_SERVICES.FreePool(). + @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last = attempt + status to report back to the ESRT table in= case + of error. This value will only be checked = when this + function returns an error. + + The return status code must fall in the ra= nge of + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERR= OR_CODE_VALUE to + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERR= OR_CODE_VALUE. + + If the value falls outside this range, it = will be converted + to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL. + + @retval EFI_SUCCESS The firmware device was successfully upda= ted + with the new firmware image. + @retval EFI_ABORTED The operation is aborted. Additional det= ails + are provided in AbortReason. + @retval EFI_INVALID_PARAMETER The Image was NULL. + @retval EFI_UNSUPPORTED The operation is not supported. + +**/ +EFI_STATUS +EFIAPI +FmpDeviceSetImageWithStatus ( + IN CONST VOID *Image, + IN UINTN ImageSize, + IN CONST VOID *VendorCode, OP= TIONAL + IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OP= TIONAL + IN UINT32 CapsuleFwVersion, + OUT CHAR16 **AbortReason, + OUT UINT32 *LastAttemptStatus + ) +{ + *LastAttemptStatus =3D LAST_ATTEMPT_STATUS_SUCCESS; + return EFI_UNSUPPORTED; } =20 diff --git a/FmpDevicePkg/Include/Library/FmpDeviceLib.h b/FmpDevicePkg/Inc= lude/Library/FmpDeviceLib.h index 9a89f5c2eec5..6abd99fa1f47 100644 --- a/FmpDevicePkg/Include/Library/FmpDeviceLib.h +++ b/FmpDevicePkg/Include/Library/FmpDeviceLib.h @@ -2,7 +2,7 @@ Provides firmware device specific services to support updates of a firmw= are image stored in a firmware device. =20 - Copyright (c) 2016, Microsoft Corporation. All rights reserved.
+ Copyright (c) Microsoft Corporation.
Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.
=20 SPDX-License-Identifier: BSD-2-Clause-Patent @@ -403,6 +403,50 @@ FmpDeviceCheckImage ( OUT UINT32 *ImageUpdatable ); =20 +/** + Checks if a new firmware image is valid for the firmware device. This + function allows firmware update operation to validate the firmware image + before FmpDeviceSetImage() is called. + + @param[in] Image Points to a new firmware image. + @param[in] ImageSize Size, in bytes, of a new firmware image. + @param[out] ImageUpdatable Indicates if a new firmware image is val= id for + a firmware update to the firmware device= . The + following values from the Firmware Manag= ement + Protocol are supported: + IMAGE_UPDATABLE_VALID + IMAGE_UPDATABLE_INVALID + IMAGE_UPDATABLE_INVALID_TYPE + IMAGE_UPDATABLE_INVALID_OLD + IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE + @param[out] LastAttemptStatus A pointer to a UINT32 that holds the las= t attempt + status to report back to the ESRT table = in case + of error. This value will only be checke= d when this + function returns an error. + + The return status code must fall in the = range of + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_E= RROR_CODE_VALUE to + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_E= RROR_CODE_VALUE. + + If the value falls outside this range, i= t will be converted + to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFU= L. + + @retval EFI_SUCCESS The image was successfully checked. Addi= tional + status information is returned in + ImageUpdatable. + @retval EFI_INVALID_PARAMETER Image is NULL. + @retval EFI_INVALID_PARAMETER ImageUpdatable is NULL. + +**/ +EFI_STATUS +EFIAPI +FmpDeviceCheckImageWithStatus ( + IN CONST VOID *Image, + IN UINTN ImageSize, + OUT UINT32 *ImageUpdatable, + OUT UINT32 *LastAttemptStatus + ); + /** Updates a firmware device with a new firmware image. This function retu= rns EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware= image @@ -466,6 +510,81 @@ FmpDeviceSetImage ( OUT CHAR16 **AbortReason ); =20 +/** + Updates a firmware device with a new firmware image. This function retu= rns + EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware= image + is updatable, the function should perform the following minimal validati= ons + before proceeding to do the firmware image update. + - Validate that the image is a supported image for this firmware devic= e. + Return EFI_ABORTED if the image is not supported. Additional detail= s + on why the image is not a supported image may be returned in AbortRe= ason. + - Validate the data from VendorCode if is not NULL. Firmware image + validation must be performed before VendorCode data validation. + VendorCode data is ignored or considered invalid if image validation + fails. Return EFI_ABORTED if the VendorCode data is invalid. + + VendorCode enables vendor to implement vendor-specific firmware image up= date + policy. Null if the caller did not specify the policy or use the defaul= t + policy. As an example, vendor can implement a policy to allow an option= to + force a firmware image update when the abort reason is due to the new fi= rmware + image version is older than the current firmware image version or bad im= age + checksum. Sensitive operations such as those wiping the entire firmware= image + and render the device to be non-functional should be encoded in the imag= e + itself rather than passed with the VendorCode. AbortReason enables vend= or to + have the option to provide a more detailed description of the abort reas= on to + the caller. + + @param[in] Image Points to the new firmware image. + @param[in] ImageSize Size, in bytes, of the new firmware image. + @param[in] VendorCode This enables vendor to implement vendor-sp= ecific + firmware image update policy. NULL indica= tes + the caller did not specify the policy or u= se the + default policy. + @param[in] Progress A function used to report the progress of + updating the firmware device with the new + firmware image. + @param[in] CapsuleFwVersion The version of the new firmware image from= the + update capsule that provided the new firmw= are + image. + @param[out] AbortReason A pointer to a pointer to a Null-terminate= d + Unicode string providing more details on a= n + aborted operation. The buffer is allocated= by + this function with + EFI_BOOT_SERVICES.AllocatePool(). It is t= he + caller's responsibility to free this buffe= r with + EFI_BOOT_SERVICES.FreePool(). + @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last = attempt + status to report back to the ESRT table in= case + of error. This value will only be checked = when this + function returns an error. + + The return status code must fall in the ra= nge of + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERR= OR_CODE_VALUE to + LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERR= OR_CODE_VALUE. + + If the value falls outside this range, it = will be converted + to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL. + + @retval EFI_SUCCESS The firmware device was successfully upda= ted + with the new firmware image. + @retval EFI_ABORTED The operation is aborted. Additional det= ails + are provided in AbortReason. + @retval EFI_INVALID_PARAMETER The Image was NULL. + @retval EFI_UNSUPPORTED The operation is not supported. + +**/ +EFI_STATUS +EFIAPI +FmpDeviceSetImageWithStatus ( + IN CONST VOID *Image, + IN UINTN ImageSize, + IN CONST VOID *VendorCode, OP= TIONAL + IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OP= TIONAL + IN UINT32 CapsuleFwVersion, + OUT CHAR16 **AbortReason, + OUT UINT32 *LastAttemptStatus + ); + /** Lock the firmware device that contains a firmware image. Once a firmwar= e device is locked, any attempts to modify the firmware image contents in = the --=20 2.28.0.windows.1