From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM10-MW2-obe.outbound.protection.outlook.com (NAM10-MW2-obe.outbound.protection.outlook.com [40.92.42.65]) by mx.groups.io with SMTP id smtpd.web11.3393.1601086835393743279 for ; Fri, 25 Sep 2020 19:20:35 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@outlook.com header.s=selector1 header.b=PLTDChne; spf=pass (domain: outlook.com, ip: 40.92.42.65, mailfrom: michael.kubacki@outlook.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=Uu4IkY1ataVWsVCaC41VQb4USj7CXq8FRhv8XCBXNsBOMVJpc40/ThJPJEijtpHQJa8uNGKg0ttiPQ+q9VMPVffovPgMixZAFPDuS1kfejF6v4BLnLqKoelffAFZZK6fy58H42PFlBXWAPXqx5MaGqFQiah+8M01dQVzdm+zel0QEJX8o+Hj+CnDeh7g9t9H34q79KnyxfPypEniotuD8oLl42NBml3qzBiZU981wJfgfzOoH205vs457mzxGoO/XmHViVP+aofIQoxcY77Fr/otbsGNlWRce+N2wzLXK5OSuj/qWgTYRFa9cCMBLsbooUfZ39A7WyKtSlp2nnSUcQ== 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=aQ7/6jDwOiD1cv1bhwyqZIW306d8/XsEDYcjJIsnzJQ=; b=Nir6d/ErE5YOtzKFfigwUJ+puFfb7vL7plEsmoVj5AD4XC/+fghpk7ihryGHHvDqejngL64lxaOxPKl7Jd2sQsxnbEZbNfXP8BGHOjQZZ2486GWTnX3DdxBftTTNQ6Fb10rP9/3M58zQeJic1hwYzpW1tl7FY2UHDemqR5D6aIXp5/o+KO2xBuCNinqr7f2QdJQyEmqg8tjIemOlF99Aqntu6Go5l/SWaigxldukafrqyooGgFpVK7lHYzqSTX9bG/9mbleJmVrSplBd6M1y5G2vPb1dLpL0HlkaAEosnd9xZAOM12xY6l8c+XKswASchXSaIYmFrj60tKwlxRa3sQ== 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=aQ7/6jDwOiD1cv1bhwyqZIW306d8/XsEDYcjJIsnzJQ=; b=PLTDChne/eBTzBkB3iF2LPR3VlmwPkrpzRQdwOiSC/htrhpedYPbYaGJbvHcIFlqPIVCsJjs0khHqd0uQCt6Hg1NbaBGpwmIIraWnd0ZpRWs+DlopLT2EKfxFTDGfVar2q2kJkneSVY4DT8g+LI11AMT/4YFj0P8h0UkXTdPtsrQnvBz633FXwjBsyYsOuZhFvSvUTQOKJUmZr6y8GWVOtwd7g2nhE84pykwHrmzzLL/sp69WEidgyTTS3FlvHkEhbUPO/EXeUQrK6BE52aI0fK8tH8tO+RxgIfmlcG/TTy7O3VoxRMkYC5TLbC/12HKwj9VQRTmL4LX09mWm8orRg== Received: from MW2NAM10FT023.eop-nam10.prod.protection.outlook.com (2a01:111:e400:7e87::51) by MW2NAM10HT073.eop-nam10.prod.protection.outlook.com (2a01:111:e400:7e87::397) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3412.21; Sat, 26 Sep 2020 02:20:34 +0000 Received: from MWHPR07MB3440.namprd07.prod.outlook.com (2a01:111:e400:7e87::4c) by MW2NAM10FT023.mail.protection.outlook.com (2a01:111:e400:7e87::154) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3412.21 via Frontend Transport; Sat, 26 Sep 2020 02:20:34 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:7A9C04B5CC296E74D348955CFDAFDC88C2C7F0874E8DB9385386E9EAAB53D144;UpperCasedChecksum:19E2838B0A060957CCEB5B285F547530490E6CE69C6070B928F75217079C85E0;SizeAsReceived:7798;Count:49 Received: from MWHPR07MB3440.namprd07.prod.outlook.com ([fe80::eda9:ccc8:2ef:2471]) by MWHPR07MB3440.namprd07.prod.outlook.com ([fe80::eda9:ccc8:2ef:2471%7]) with mapi id 15.20.3391.026; Sat, 26 Sep 2020 02:20:34 +0000 From: "Michael Kubacki" To: devel@edk2.groups.io CC: Liming Gao , Michael D Kinney , Guomin Jiang , Wei6 Xu Subject: [PATCH v4 6/6] FmpDevicePkg/FmpDeviceLib: Add Last Attempt Status to Check/Set API Date: Fri, 25 Sep 2020 19:19:44 -0700 Message-ID: X-Mailer: git-send-email 2.28.0.windows.1 In-Reply-To: <20200926021944.3575-1-michael.kubacki@outlook.com> References: <20200926021944.3575-1-michael.kubacki@outlook.com> X-ClientProxiedBy: CO2PR04CA0154.namprd04.prod.outlook.com (2603:10b6:104::32) To MWHPR07MB3440.namprd07.prod.outlook.com (2603:10b6:301:69::28) Return-Path: michael.kubacki@outlook.com X-Microsoft-Original-Message-ID: <20200926021944.3575-7-michael.kubacki@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from localhost.localdomain (2001:4898:80e8:1:9df7:74f4:6652:1fbe) by CO2PR04CA0154.namprd04.prod.outlook.com (2603:10b6:104::32) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3391.14 via Frontend Transport; Sat, 26 Sep 2020 02:20:33 +0000 X-Mailer: git-send-email 2.28.0.windows.1 X-Microsoft-Original-Message-ID: <20200926021944.3575-7-michael.kubacki@outlook.com> X-TMN: [JJR483daz4pY9+0UOoM6c6I4H18eTglKCbMUvxN/hBNFGGYLsBewZq411qmvu5s+] X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 49 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: 7141775f-eaba-4fc7-0748-08d861c2bf95 X-MS-TrafficTypeDiagnostic: MW2NAM10HT073: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: IAwDcsRybKXVH4xZ5BjNXpBtlcN+CwJaqkwz5qWQeu71QAuozvZ6A9QuU3hfyuTs5DZdeN3nE4WOusDj1YYGUvPwmh4W+XFZAqCtxdJ/nTmOrDh3qt0vXDIUJyxe7gYxetFLLhlJTar+Rkt5FpAn0kQuCDf6P4+OU0/HVdxbxvCoa/BEg7KdmZ3QhltWTIUxTcPl4MkxBglRt6dtWt+W6g== X-MS-Exchange-AntiSpam-MessageData: G/OaLLrN2J2+v9UlMl91yJ9OfQTLMjlQIZdNUmHxmrjPpXYY7+j14rVddR+pis1uHa1lkp25pSKhDxF4l8dD1TPF/SyY22uwxmoMSQ5YtYppDfBhah4ENjhWmYtCm+AmMwQYzknOpq7lKTOpS2cU6UTgn5Crn4RJjnv19dsHY9b2nCqtDJbH7huQHLqlWHJ4odT9q2bjoISVeIBwztZcSA== X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 7141775f-eaba-4fc7-0748-08d861c2bf95 X-MS-Exchange-CrossTenant-OriginalArrivalTime: 26 Sep 2020 02:20:34.0698 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-AuthSource: MW2NAM10FT023.eop-nam10.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: MW2NAM10HT073 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 --- FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c | 132 +++++++++++++++= ++++- FmpDevicePkg/Include/Library/FmpDeviceLib.h | 121 +++++++++++++++= ++- 2 files changed, 251 insertions(+), 2 deletions(-) diff --git a/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c b/FmpDevi= cePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c index 316de12e910c..4e1ce8bf2294 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 /** @@ -410,6 +411,55 @@ FmpDeviceCheckImage ( return EFI_SUCCESS; } =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 + ) +{ + *LastAttemptStatus =3D LAST_ATTEMPT_STATUS_SUCCESS; + + return EFI_SUCCESS; +} + /** 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 @@ -476,6 +526,86 @@ FmpDeviceSetImage ( return EFI_UNSUPPORTED; } =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 + ) +{ + *LastAttemptStatus =3D LAST_ATTEMPT_STATUS_SUCCESS; + + return EFI_UNSUPPORTED; +} + /** 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 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