Re: [Patch v3 3/3] SignedCapsulePkg/PlatformFlashAccessLib: Add progress API

["Yao, Jiewen" <jiewen.yao@intel.com>]

Reviewed-by: Jiewen.yao@intel.com

> -----Original Message-----
> From: Kinney, Michael D
> Sent: Thursday, May 24, 2018 11:16 PM
> To: edk2-devel@lists.01.org
> Cc: Yao, Jiewen <jiewen.yao@intel.com>
> Subject: [Patch v3 3/3] SignedCapsulePkg/PlatformFlashAccessLib: Add progress
> API
> 
> https://bugzilla.tianocore.org/show_bug.cgi?id=801
> 
> Add a new API to the PlatformFlashAccessLib that passes
> in an optional Progress() function along with a start and
> end percentage to call the Progress() function with.
> If the Progress() function is not NULL, then it is the
> Progress() function that was passed into the Firmware
> Management Protocol SetImage() services and is used
> to update the user on the progress as a firmware device
> is updated with a firmware image.
> 
> Implementations of the PlatformFlashAccessLib are
> recommended to call the Progress() function as work
> is performed to update to contents of a firmware
> storage device.
> 
> Cc: Jiewen Yao <jiewen.yao@intel.com>
> Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
> Contributed-under: TianoCore Contribution Agreement 1.1
> ---
>  .../Include/Library/PlatformFlashAccessLib.h       | 49 ++++++++++++++-
>  .../PlatformFlashAccessLibNull.c                   | 70
> +++++++++++++++++++---
>  2 files changed, 110 insertions(+), 9 deletions(-)
> 
> diff --git a/SignedCapsulePkg/Include/Library/PlatformFlashAccessLib.h
> b/SignedCapsulePkg/Include/Library/PlatformFlashAccessLib.h
> index 0a8858e4c4..e3308251c2 100644
> --- a/SignedCapsulePkg/Include/Library/PlatformFlashAccessLib.h
> +++ b/SignedCapsulePkg/Include/Library/PlatformFlashAccessLib.h
> @@ -1,7 +1,7 @@
>  /** @file
>    Platform flash device access library.
> 
> -  Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
> +  Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
>    This program and the accompanying materials
>    are licensed and made available under the terms and conditions of the BSD
> License
>    which accompanies this distribution.  The full text of the license may be
> found at
> @@ -16,6 +16,8 @@
>  #ifndef __PLATFORM_FLASH_ACCESS_LIB_H__
>  #define __PLATFORM_FLASH_ACCESS_LIB_H__
> 
> +#include <Protocol/FirmwareManagement.h>
> +
>  typedef enum {
>    FlashAddressTypeRelativeAddress,
>    FlashAddressTypeAbsoluteAddress,
> @@ -31,7 +33,7 @@ typedef enum {
>  } PLATFORM_FIRMWARE_TYPE;
> 
>  /**
> -  Perform flash write opreation.
> +  Perform flash write operation.
> 
>    @param[in] FirmwareType      The type of firmware.
>    @param[in] FlashAddress      The address of flash device to be accessed.
> @@ -54,4 +56,47 @@ PerformFlashWrite (
>    IN UINTN                        Length
>    );
> 
> +/**
> +  Perform flash write operation with progress indicator.  The start and end
> +  completion percentage values are passed into this function.  If the
> requested
> +  flash write operation is broken up, then completion percentage between the
> +  start and end values may be passed to the provided Progress function.  The
> +  caller of this function is required to call the Progress function for the
> +  start and end completion percentage values.  This allows the Progress,
> +  StartPercentage, and EndPercentage parameters to be ignored if the
> requested
> +  flash write operation can not be broken up
> +
> +  @param[in] FirmwareType      The type of firmware.
> +  @param[in] FlashAddress      The address of flash device to be accessed.
> +  @param[in] FlashAddressType  The type of flash device address.
> +  @param[in] Buffer            The pointer to the data buffer.
> +  @param[in] Length            The length of data buffer in bytes.
> +  @param[in] Progress          A function used report the progress of the
> +                               firmware update.  This is an optional
> parameter
> +                               that may be NULL.
> +  @param[in] StartPercentage   The start completion percentage value that
> may
> +                               be used to report progress during the flash
> +                               write operation.
> +  @param[in] EndPercentage     The end completion percentage value that
> may
> +                               be used to report progress during the flash
> +                               write operation.
> +
> +  @retval EFI_SUCCESS           The operation returns successfully.
> +  @retval EFI_WRITE_PROTECTED   The flash device is read only.
> +  @retval EFI_UNSUPPORTED       The flash device access is unsupported.
> +  @retval EFI_INVALID_PARAMETER The input parameter is not valid.
> +**/
> +EFI_STATUS
> +EFIAPI
> +PerformFlashWriteWithProgress (
> +  IN PLATFORM_FIRMWARE_TYPE                         FirmwareType,
> +  IN EFI_PHYSICAL_ADDRESS                           FlashAddress,
> +  IN FLASH_ADDRESS_TYPE
> FlashAddressType,
> +  IN VOID                                           *Buffer,
> +  IN UINTN                                          Length,
> +  IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,
> OPTIONAL
> +  IN UINTN                                          StartPercentage,
> +  IN UINTN                                          EndPercentage
> +  );
> +
>  #endif
> diff --git
> a/SignedCapsulePkg/Library/PlatformFlashAccessLibNull/PlatformFlashAccessLib
> Null.c
> b/SignedCapsulePkg/Library/PlatformFlashAccessLibNull/PlatformFlashAccessLib
> Null.c
> index b34ebbba1e..854f108cf4 100644
> ---
> a/SignedCapsulePkg/Library/PlatformFlashAccessLibNull/PlatformFlashAccessLib
> Null.c
> +++
> b/SignedCapsulePkg/Library/PlatformFlashAccessLibNull/PlatformFlashAccessLib
> Null.c
> @@ -1,7 +1,7 @@
>  /** @file
>    Platform flash device access library NULL instance.
> 
> -  Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
> +  Copyright (c) 2016 - 2018, Intel Corporation. All rights reserved.<BR>
>    This program and the accompanying materials
>    are licensed and made available under the terms and conditions of the BSD
> License
>    which accompanies this distribution.  The full text of the license may be
> found at
> @@ -20,7 +20,57 @@
>  UINT64 mInternalFdAddress;
> 
>  /**
> -  Perform flash write opreation.
> +  Perform flash write operation with progress indicator.  The start and end
> +  completion percentage values are passed into this function.  If the
> requested
> +  flash write operation is broken up, then completion percentage between the
> +  start and end values may be passed to the provided Progress function.  The
> +  caller of this function is required to call the Progress function for the
> +  start and end completion percentage values.  This allows the Progress,
> +  StartPercentage, and EndPercentage parameters to be ignored if the
> requested
> +  flash write operation can not be broken up
> +
> +  @param[in] FirmwareType      The type of firmware.
> +  @param[in] FlashAddress      The address of flash device to be accessed.
> +  @param[in] FlashAddressType  The type of flash device address.
> +  @param[in] Buffer            The pointer to the data buffer.
> +  @param[in] Length            The length of data buffer in bytes.
> +  @param[in] Progress          A function used report the progress of the
> +                               firmware update.  This is an optional
> parameter
> +                               that may be NULL.
> +  @param[in] StartPercentage   The start completion percentage value that
> may
> +                               be used to report progress during the flash
> +                               write operation.
> +  @param[in] EndPercentage     The end completion percentage value that
> may
> +                               be used to report progress during the flash
> +                               write operation.
> +
> +  @retval EFI_SUCCESS           The operation returns successfully.
> +  @retval EFI_WRITE_PROTECTED   The flash device is read only.
> +  @retval EFI_UNSUPPORTED       The flash device access is unsupported.
> +  @retval EFI_INVALID_PARAMETER The input parameter is not valid.
> +**/
> +EFI_STATUS
> +EFIAPI
> +PerformFlashWriteWithProgress (
> +  IN PLATFORM_FIRMWARE_TYPE                         FirmwareType,
> +  IN EFI_PHYSICAL_ADDRESS                           FlashAddress,
> +  IN FLASH_ADDRESS_TYPE
> FlashAddressType,
> +  IN VOID                                           *Buffer,
> +  IN UINTN                                          Length,
> +  IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,
> OPTIONAL
> +  IN UINTN                                          StartPercentage,
> +  IN UINTN                                          EndPercentage
> +  )
> +{
> +  if (FlashAddressType == FlashAddressTypeRelativeAddress) {
> +    FlashAddress = FlashAddress + mInternalFdAddress;
> +  }
> +  CopyMem((VOID *)(UINTN)(FlashAddress), Buffer, Length);
> +  return EFI_SUCCESS;
> +}
> +
> +/**
> +  Perform flash write operation.
> 
>    @param[in] FirmwareType      The type of firmware.
>    @param[in] FlashAddress      The address of flash device to be accessed.
> @@ -43,9 +93,15 @@ PerformFlashWrite (
>    IN UINTN                        Length
>    )
>  {
> -  if (FlashAddressType == FlashAddressTypeRelativeAddress) {
> -    FlashAddress = FlashAddress + mInternalFdAddress;
> -  }
> -  CopyMem((VOID *)(UINTN)(FlashAddress), Buffer, Length);
> -  return EFI_SUCCESS;
> +  return PerformFlashWriteWithProgress (
> +           FirmwareType,
> +           FlashAddress,
> +           FlashAddressType,
> +           Buffer,
> +           Length,
> +           NULL,
> +           0,
> +           0
> +           );
>  }
> +
> --
> 2.14.2.windows.3