FmpDevicePkg/FmpDeviceLib: Add Last Attempt Status to Check/Set API

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 <gaoliming@byosoft.com.cn>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Cc: Guomin Jiang <guomin.jiang@intel.com>
Cc: Wei6 Xu <wei6.xu@intel.com>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
Acked-by: Liming Gao <gaoliming@byosoft.com.cn>
Reviewed-by: Wei6 Xu <wei6.xu@intel.com>
Reviewed-by: Michael D Kinney <michael.d.kinney@intel.com>

diff --git a/FmpDevicePkg/Include/Library/FmpDeviceLib.h b/FmpDevicePkg/Include/Library/FmpDeviceLib.h
index 9a89f5c2eec5c7e33bfe91f26b6824d6999c097d..6abd99fa1f47aab79cea2fbe098f7bed8956a833 100644 (file)
--- 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 firmware\r
   image stored in a firmware device.\r
 \r
-  Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
+  Copyright (c) Microsoft Corporation.<BR>\r
   Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
 \r
   SPDX-License-Identifier: BSD-2-Clause-Patent\r
@@ -403,6 +403,50 @@ FmpDeviceCheckImage (
   OUT UINT32      *ImageUpdatable\r
   );\r
 \r
+/**\r
+  Checks if a new firmware image is valid for the firmware device.  This\r
+  function allows firmware update operation to validate the firmware image\r
+  before FmpDeviceSetImage() is called.\r
+\r
+  @param[in]  Image               Points to a new firmware image.\r
+  @param[in]  ImageSize           Size, in bytes, of a new firmware image.\r
+  @param[out] ImageUpdatable      Indicates if a new firmware image is valid for\r
+                                  a firmware update to the firmware device.  The\r
+                                  following values from the Firmware Management\r
+                                  Protocol are supported:\r
+                                    IMAGE_UPDATABLE_VALID\r
+                                    IMAGE_UPDATABLE_INVALID\r
+                                    IMAGE_UPDATABLE_INVALID_TYPE\r
+                                    IMAGE_UPDATABLE_INVALID_OLD\r
+                                    IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
+  @param[out] LastAttemptStatus   A pointer to a UINT32 that holds the last attempt\r
+                                  status to report back to the ESRT table in case\r
+                                  of error. This value will only be checked when this\r
+                                  function returns an error.\r
+\r
+                                  The return status code must fall in the range of\r
+                                  LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+                                  LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+                                  If the value falls outside this range, it will be converted\r
+                                  to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+  @retval EFI_SUCCESS            The image was successfully checked.  Additional\r
+                                 status information is returned in\r
+                                 ImageUpdatable.\r
+  @retval EFI_INVALID_PARAMETER  Image is NULL.\r
+  @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceCheckImageWithStatus (\r
+  IN  CONST VOID  *Image,\r
+  IN  UINTN       ImageSize,\r
+  OUT UINT32      *ImageUpdatable,\r
+  OUT UINT32      *LastAttemptStatus\r
+  );\r
+\r
 /**\r
   Updates a firmware device with a new firmware image.  This function returns\r
   EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image\r
@@ -466,6 +510,81 @@ FmpDeviceSetImage (
   OUT CHAR16                                         **AbortReason\r
   );\r
 \r
+/**\r
+  Updates a firmware device with a new firmware image.  This function returns\r
+  EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image\r
+  is updatable, the function should perform the following minimal validations\r
+  before proceeding to do the firmware image update.\r
+    - Validate that the image is a supported image for this firmware device.\r
+      Return EFI_ABORTED if the image is not supported.  Additional details\r
+      on why the image is not a supported image may be returned in AbortReason.\r
+    - Validate the data from VendorCode if is not NULL.  Firmware image\r
+      validation must be performed before VendorCode data validation.\r
+      VendorCode data is ignored or considered invalid if image validation\r
+      fails.  Return EFI_ABORTED if the VendorCode data is invalid.\r
+\r
+  VendorCode enables vendor to implement vendor-specific firmware image update\r
+  policy.  Null if the caller did not specify the policy or use the default\r
+  policy.  As an example, vendor can implement a policy to allow an option to\r
+  force a firmware image update when the abort reason is due to the new firmware\r
+  image version is older than the current firmware image version or bad image\r
+  checksum.  Sensitive operations such as those wiping the entire firmware image\r
+  and render the device to be non-functional should be encoded in the image\r
+  itself rather than passed with the VendorCode.  AbortReason enables vendor to\r
+  have the option to provide a more detailed description of the abort reason to\r
+  the caller.\r
+\r
+  @param[in]  Image             Points to the new firmware image.\r
+  @param[in]  ImageSize         Size, in bytes, of the new firmware image.\r
+  @param[in]  VendorCode        This enables vendor to implement vendor-specific\r
+                                firmware image update policy.  NULL indicates\r
+                                the caller did not specify the policy or use the\r
+                                default policy.\r
+  @param[in]  Progress          A function used to report the progress of\r
+                                updating the firmware device with the new\r
+                                firmware image.\r
+  @param[in]  CapsuleFwVersion  The version of the new firmware image from the\r
+                                update capsule that provided the new firmware\r
+                                image.\r
+  @param[out] AbortReason       A pointer to a pointer to a Null-terminated\r
+                                Unicode string providing more details on an\r
+                                aborted operation. The buffer is allocated by\r
+                                this function with\r
+                                EFI_BOOT_SERVICES.AllocatePool().  It is the\r
+                                caller's responsibility to free this buffer with\r
+                                EFI_BOOT_SERVICES.FreePool().\r
+  @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
+                                status to report back to the ESRT table in case\r
+                                of error. This value will only be checked when this\r
+                                function returns an error.\r
+\r
+                                The return status code must fall in the range of\r
+                                LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+                                LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+                                If the value falls outside this range, it will be converted\r
+                                to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+  @retval EFI_SUCCESS            The firmware device was successfully updated\r
+                                 with the new firmware image.\r
+  @retval EFI_ABORTED            The operation is aborted.  Additional details\r
+                                 are provided in AbortReason.\r
+  @retval EFI_INVALID_PARAMETER  The Image was NULL.\r
+  @retval EFI_UNSUPPORTED        The operation is not supported.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceSetImageWithStatus (\r
+  IN  CONST VOID                                     *Image,\r
+  IN  UINTN                                          ImageSize,\r
+  IN  CONST VOID                                     *VendorCode,       OPTIONAL\r
+  IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL\r
+  IN  UINT32                                         CapsuleFwVersion,\r
+  OUT CHAR16                                         **AbortReason,\r
+  OUT UINT32                                         *LastAttemptStatus\r
+  );\r
+\r
 /**\r
   Lock the firmware device that contains a firmware image.  Once a firmware\r
   device is locked, any attempts to modify the firmware image contents in the\r

diff --git a/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c b/FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c
index 316de12e910c6e23328592401d10f9f924416363..f4f57b29bdb1af9b99d1319269a11847df53b973 100644 (file)
--- 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 firmware\r
   image stored in a firmware device.\r
 \r
-  Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
+  Copyright (c) Microsoft Corporation.<BR>\r
   Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
 \r
   SPDX-License-Identifier: BSD-2-Clause-Patent\r
@@ -10,6 +10,7 @@
 **/\r
 \r
 #include <PiDxe.h>\r
+#include <Guid/SystemResourceTable.h>\r
 #include <Library/FmpDeviceLib.h>\r
 \r
 /**\r
@@ -407,6 +408,57 @@ FmpDeviceCheckImage (
   OUT UINT32      *ImageUpdatable\r
   )\r
 {\r
+  UINT32  LastAttemptStatus;\r
+\r
+  return FmpDeviceCheckImageWithStatus (Image, ImageSize, ImageUpdatable, &LastAttemptStatus);\r
+}\r
+\r
+/**\r
+  Checks if a new firmware image is valid for the firmware device.  This\r
+  function allows firmware update operation to validate the firmware image\r
+  before FmpDeviceSetImage() is called.\r
+\r
+  @param[in]  Image               Points to a new firmware image.\r
+  @param[in]  ImageSize           Size, in bytes, of a new firmware image.\r
+  @param[out] ImageUpdatable      Indicates if a new firmware image is valid for\r
+                                  a firmware update to the firmware device.  The\r
+                                  following values from the Firmware Management\r
+                                  Protocol are supported:\r
+                                    IMAGE_UPDATABLE_VALID\r
+                                    IMAGE_UPDATABLE_INVALID\r
+                                    IMAGE_UPDATABLE_INVALID_TYPE\r
+                                    IMAGE_UPDATABLE_INVALID_OLD\r
+                                    IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
+  @param[out] LastAttemptStatus   A pointer to a UINT32 that holds the last attempt\r
+                                  status to report back to the ESRT table in case\r
+                                  of error. This value will only be checked when this\r
+                                  function returns an error.\r
+\r
+                                  The return status code must fall in the range of\r
+                                  LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+                                  LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+                                  If the value falls outside this range, it will be converted\r
+                                  to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+  @retval EFI_SUCCESS            The image was successfully checked.  Additional\r
+                                 status information is returned in\r
+                                 ImageUpdatable.\r
+  @retval EFI_INVALID_PARAMETER  Image is NULL.\r
+  @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceCheckImageWithStatus (\r
+  IN  CONST VOID  *Image,\r
+  IN  UINTN       ImageSize,\r
+  OUT UINT32      *ImageUpdatable,\r
+  OUT UINT32      *LastAttemptStatus\r
+  )\r
+{\r
+  *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;\r
+\r
   return EFI_SUCCESS;\r
 }\r
 \r
@@ -473,6 +525,96 @@ FmpDeviceSetImage (
   OUT CHAR16                                         **AbortReason\r
   )\r
 {\r
+  UINT32  LastAttemptStatus;\r
+\r
+  return  FmpDeviceSetImageWithStatus (\r
+            Image,\r
+            ImageSize,\r
+            VendorCode,\r
+            Progress,\r
+            CapsuleFwVersion,\r
+            AbortReason,\r
+            &LastAttemptStatus\r
+            );\r
+}\r
+\r
+/**\r
+  Updates a firmware device with a new firmware image.  This function returns\r
+  EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image\r
+  is updatable, the function should perform the following minimal validations\r
+  before proceeding to do the firmware image update.\r
+    - Validate that the image is a supported image for this firmware device.\r
+      Return EFI_ABORTED if the image is not supported.  Additional details\r
+      on why the image is not a supported image may be returned in AbortReason.\r
+    - Validate the data from VendorCode if is not NULL.  Firmware image\r
+      validation must be performed before VendorCode data validation.\r
+      VendorCode data is ignored or considered invalid if image validation\r
+      fails.  Return EFI_ABORTED if the VendorCode data is invalid.\r
+\r
+  VendorCode enables vendor to implement vendor-specific firmware image update\r
+  policy.  Null if the caller did not specify the policy or use the default\r
+  policy.  As an example, vendor can implement a policy to allow an option to\r
+  force a firmware image update when the abort reason is due to the new firmware\r
+  image version is older than the current firmware image version or bad image\r
+  checksum.  Sensitive operations such as those wiping the entire firmware image\r
+  and render the device to be non-functional should be encoded in the image\r
+  itself rather than passed with the VendorCode.  AbortReason enables vendor to\r
+  have the option to provide a more detailed description of the abort reason to\r
+  the caller.\r
+\r
+  @param[in]  Image             Points to the new firmware image.\r
+  @param[in]  ImageSize         Size, in bytes, of the new firmware image.\r
+  @param[in]  VendorCode        This enables vendor to implement vendor-specific\r
+                                firmware image update policy.  NULL indicates\r
+                                the caller did not specify the policy or use the\r
+                                default policy.\r
+  @param[in]  Progress          A function used to report the progress of\r
+                                updating the firmware device with the new\r
+                                firmware image.\r
+  @param[in]  CapsuleFwVersion  The version of the new firmware image from the\r
+                                update capsule that provided the new firmware\r
+                                image.\r
+  @param[out] AbortReason       A pointer to a pointer to a Null-terminated\r
+                                Unicode string providing more details on an\r
+                                aborted operation. The buffer is allocated by\r
+                                this function with\r
+                                EFI_BOOT_SERVICES.AllocatePool().  It is the\r
+                                caller's responsibility to free this buffer with\r
+                                EFI_BOOT_SERVICES.FreePool().\r
+  @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt\r
+                                status to report back to the ESRT table in case\r
+                                of error. This value will only be checked when this\r
+                                function returns an error.\r
+\r
+                                The return status code must fall in the range of\r
+                                LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to\r
+                                LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.\r
+\r
+                                If the value falls outside this range, it will be converted\r
+                                to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.\r
+\r
+  @retval EFI_SUCCESS            The firmware device was successfully updated\r
+                                 with the new firmware image.\r
+  @retval EFI_ABORTED            The operation is aborted.  Additional details\r
+                                 are provided in AbortReason.\r
+  @retval EFI_INVALID_PARAMETER  The Image was NULL.\r
+  @retval EFI_UNSUPPORTED        The operation is not supported.\r
+\r
+**/\r
+EFI_STATUS\r
+EFIAPI\r
+FmpDeviceSetImageWithStatus (\r
+  IN  CONST VOID                                     *Image,\r
+  IN  UINTN                                          ImageSize,\r
+  IN  CONST VOID                                     *VendorCode,       OPTIONAL\r
+  IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL\r
+  IN  UINT32                                         CapsuleFwVersion,\r
+  OUT CHAR16                                         **AbortReason,\r
+  OUT UINT32                                         *LastAttemptStatus\r
+  )\r
+{\r
+  *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;\r
+\r
   return EFI_UNSUPPORTED;\r
 }\r
 \r