From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from NAM04-BN8-obe.outbound.protection.outlook.com (NAM04-BN8-obe.outbound.protection.outlook.com [40.92.47.90]) by mx.groups.io with SMTP id smtpd.web11.497.1602796340905897102 for ; Thu, 15 Oct 2020 14:12:21 -0700 Authentication-Results: mx.groups.io; dkim=fail reason="body hash did not verify" header.i=@outlook.com header.s=selector1 header.b=QTteH+H3; spf=pass (domain: outlook.com, ip: 40.92.47.90, mailfrom: michael.kubacki@outlook.com) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=OmIvppzgRrFM1UdcV86XCLyf80gZ81M92EEgpq4MO/lbTz8AQd0j0/Uw2Inx99ama5MJn9bhjTEV6Vg+nBstiTP4poIc4tbkMy0R5s9H3Tf3TRnntDfq48YXx9IE+reIjtqiPtMIPlK0K1DwhQt/N6wQHFq6G6l0AWgfXR676t8I9Dn2wjz+QWHdw+JKqBlgqmUALHjKcRuyeclI0qN59WyFY7X6oHKLlvcOryhMIHCrOnHrYHaNEkdn6WJxFFmehMM/6qQtp5sNkcDG0oif4tb1KAbyZ6qfQPOOTtCky2KI3Q0eTbnvBpyo1bjubeVn7/BOEdK66dnenA9OGG0wUA== 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=j7yPl4f9b7WdNiLzNVgOpk0AideH7J/XFMg/1AUh/52m2ptob/IQIUC70ip9yX6/DOO8RgcQuKQ3Kj85lR7YEoYt6s1wiY1XigON2PS0Qm6rj7qtQ61SldSzb5pLLeu/vVYKgAp07vdKpfOCk4S9OimFoaVYQZgF/bA7WhHulnHyK+xSziGjgDDKpuz7RbR2qkjYBrgithX6kjGq2E13w7juxMKpRK2RGxNHmq1+LosVc8SvIsA0YV/H+B7w9sgvTYPcLo0Q2i10jgM3Ih00HIGxf/L28SYMMsvnTxq/WbmASD9IiH1KYImREpH8Pzd4ybELSmODIhyiWmVwETDG6Q== 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=QTteH+H32Tz8n5bf/xI9HZ1FVDZgJtYdgNonUXqdCKtyXAdX2/Y7cqvqzs8U7xtzh8Bt3goIq7cccNXdQsKBtM4akHYEHhSp0FEK1kgo5hrwWkVbs9/wVqI8t+4Rt55GWklKTrpF5qOtYpn9E7WDQ0Q4gZEmHso3PVgcAfYvpCrBWgmvQgMHyUOLGkNfOLlgc4YOj9/hbox7JTGI7lFAV0DW8E0wPXxedwOQ+ZrzzMdbEIm0ujwPg5EXYdbVRQK8k3CAUr3aNh9oUiU3EgScqCVchhBFu8mcQtB6fVWQ6oGz/JHDcIREsLvsGAJOfk2JeC9ls8aFHLqd3mlnep35nQ== Received: from DM6NAM04FT027.eop-NAM04.prod.protection.outlook.com (2a01:111:e400:7ea3::47) by DM6NAM04HT109.eop-NAM04.prod.protection.outlook.com (2a01:111:e400:7ea3::144) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3455.27; Thu, 15 Oct 2020 21:12:19 +0000 Received: from MWHPR07MB3440.namprd07.prod.outlook.com (2a01:111:e400:7ea3::53) by DM6NAM04FT027.mail.protection.outlook.com (2a01:111:e400:7ea3::334) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3455.27 via Frontend Transport; Thu, 15 Oct 2020 21:12:19 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:97EBC7EA8A91046EE602AC053B0438ABFF4A1C202284800C86BB3424E69E446F;UpperCasedChecksum:3864B6FC1DAE4235F7BB286D2BC3F23BAE8E422B4A10DC72C4BB1D9DFF273E4A;SizeAsReceived:7683;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.3455.031; Thu, 15 Oct 2020 21:12:19 +0000 From: "Michael Kubacki" To: devel@edk2.groups.io CC: Liming Gao , Michael D Kinney , Guomin Jiang , Wei6 Xu Subject: [PATCH v5 6/6] FmpDevicePkg/FmpDeviceLib: Add Last Attempt Status to Check/Set API Date: Thu, 15 Oct 2020 14:11:21 -0700 Message-ID: X-Mailer: git-send-email 2.28.0.windows.1 In-Reply-To: <20201015211121.1927-1-michael.kubacki@outlook.com> References: <20201015211121.1927-1-michael.kubacki@outlook.com> X-TMN: [xYs9CcK5Io0dmYPvxJntKd98W9zfrSW35Wdbqb9tiB8MSLrsrl96jRq5z+48gBeh] X-ClientProxiedBy: MWHPR22CA0029.namprd22.prod.outlook.com (2603:10b6:300:69::15) To MWHPR07MB3440.namprd07.prod.outlook.com (2603:10b6:301:69::28) Return-Path: michael.kubacki@outlook.com X-Microsoft-Original-Message-ID: <20201015211121.1927-7-michael.kubacki@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from localhost.localdomain (2001:4898:80e8:8:d168:ab8a:5f17:7fc6) by MWHPR22CA0029.namprd22.prod.outlook.com (2603:10b6:300:69::15) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3477.20 via Frontend Transport; Thu, 15 Oct 2020 21:12:19 +0000 X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 47 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: 94580127-01b0-4a34-b0ed-08d8714f004f X-MS-TrafficTypeDiagnostic: DM6NAM04HT109: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: oodgGPk6dkw0VMnXJTKRNAy/g2q+4J07lI2c7nAA1xFyGN0R6tLezRX7+VtC9yENWXWqMQXV52bvmGy0lFD0/kcPC4slXUsgehha6tEkAfBdS2MZ5y5wx0eP9oyki0Pt5NMXTAlhWUIPjBPI3Ap3iJThfXQ3bkr7P0mTAAxnp55EZHhFQXtbs+Jl0PukE+4Roq7IaJQKaVm2OzwAIEqhAg== X-MS-Exchange-AntiSpam-MessageData: FSpVDFXFX1FAyn1WhaN/0XA1TyEMVZU2wRt1oScpi+KTKzncrygV1JAIRZgLCrlOd01DLpGRUcb4K6M4L+FGDVvnYUJAJtw5j0GKGlH42X2tvqk/qd2yERWIxegR0nd/vW63Yv1gmjYOTOJOEqD5JQbxxDySGs7VntaGMwkCT6a6TsRtnTjHu9eA0lbateeyZtpLbdq+pJFTmFGrMILERA== X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 94580127-01b0-4a34-b0ed-08d8714f004f X-MS-Exchange-CrossTenant-OriginalArrivalTime: 15 Oct 2020 21:12:19.6881 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-AuthSource: DM6NAM04FT027.eop-NAM04.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: DM6NAM04HT109 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