FmpDevicePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / FmpDevicePkg / Include / Library / FmpDeviceLib.h

/** @file\r
  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) 2018, Intel Corporation. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __FMP_DEVICE_LIB__\r
#define __FMP_DEVICE_LIB__\r
\r
#include <Protocol/FirmwareManagement.h>\r
\r
/**\r
  Callback function that installs a Firmware Management Protocol instance onto\r
  a handle.\r
\r
  @param[in]  Handle  The device handle to install a Firmware Management\r
                      Protocol instance.\r
\r
  @retval  EFI_SUCCESS            A Firmware Management Protocol instance was\r
                                  installed onto Handle.\r
  @retval  EFI_INVALID_PARAMETER  Handle is invalid\r
  @retval  other                  A Firmware Management Protocol instance could\r
                                  not be installed onto Handle.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER)(\r
  IN  EFI_HANDLE      Handle\r
  );\r
\r
/**\r
  Provide a function to install the Firmware Management Protocol instance onto a\r
  device handle when the device is managed by a driver that follows the UEFI\r
  Driver Model.  If the device is not managed by a driver that follows the UEFI\r
  Driver Model, then EFI_UNSUPPORTED is returned.\r
\r
  @param[in] FmpInstaller  Function that installs the Firmware Management\r
                           Protocol.\r
\r
  @retval EFI_SUCCESS      The device is managed by a driver that follows the\r
                           UEFI Driver Model.  FmpInstaller must be called on\r
                           each Driver Binding Start().\r
  @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows\r
                           the UEFI Driver Model.\r
  @retval other            The Firmware Management Protocol for this firmware\r
                           device is not installed.  The firmware device is\r
                           still locked using FmpDeviceLock().\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
RegisterFmpInstaller (\r
  IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER  FmpInstaller\r
  );\r
\r
/**\r
  Returns the size, in bytes, of the firmware image currently stored in the\r
  firmware device.  This function is used to by the GetImage() and\r
  GetImageInfo() services of the Firmware Management Protocol.  If the image\r
  size can not be determined from the firmware device, then 0 must be returned.\r
\r
  @param[out] Size  Pointer to the size, in bytes, of the firmware image\r
                    currently stored in the firmware device.\r
\r
  @retval EFI_SUCCESS            The size of the firmware image currently\r
                                 stored in the firmware device was returned.\r
  @retval EFI_INVALID_PARAMETER  Size is NULL.\r
  @retval EFI_UNSUPPORTED        The firmware device does not support reporting\r
                                 the size of the currently stored firmware image.\r
  @retval EFI_DEVICE_ERROR       An error occured attempting to determine the\r
                                 size of the firmware image currently stored in\r
                                 in the firmware device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetSize (\r
  OUT UINTN  *Size\r
  );\r
\r
/**\r
  Returns the GUID value used to fill in the ImageTypeId field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_UNSUPPORTED is returned,\r
  then the ImageTypeId field is set to gEfiCallerIdGuid.  If EFI_SUCCESS is\r
  returned, then ImageTypeId is set to the Guid returned from this function.\r
\r
  @param[out] Guid  Double pointer to a GUID value that is updated to point to\r
                    to a GUID value.  The GUID value is not allocated and must\r
                    not be modified or freed by the caller.\r
\r
  @retval EFI_SUCCESS      EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
                           to the returned Guid value.\r
  @retval EFI_UNSUPPORTED  EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
                           to gEfiCallerIdGuid.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetImageTypeIdGuidPtr (\r
  OUT EFI_GUID  **Guid\r
  );\r
\r
/**\r
  Returns values used to fill in the AttributesSupported and AttributesSettings\r
  fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the\r
  GetImageInfo() service of the Firmware Management Protocol.  The following\r
  bit values from the Firmware Management Protocol may be combined:\r
    IMAGE_ATTRIBUTE_IMAGE_UPDATABLE\r
    IMAGE_ATTRIBUTE_RESET_REQUIRED\r
    IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED\r
    IMAGE_ATTRIBUTE_IN_USE\r
    IMAGE_ATTRIBUTE_UEFI_IMAGE\r
\r
  @param[out] Supported  Attributes supported by this firmware device.\r
  @param[out] Setting    Attributes settings for this firmware device.\r
\r
  @retval EFI_SUCCESS            The attributes supported by the firmware\r
                                 device were returned.\r
  @retval EFI_INVALID_PARAMETER  Supported is NULL.\r
  @retval EFI_INVALID_PARAMETER  Setting is NULL.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetAttributes (\r
  OUT UINT64    *Supported,\r
  OUT UINT64    *Setting\r
  );\r
\r
/**\r
  Returns the value used to fill in the LowestSupportedVersion field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then\r
  the firmware device supports a method to report the LowestSupportedVersion\r
  value from the currently stored firmware image.  If the value can not be\r
  reported for the firmware image currently stored in the firmware device, then\r
  EFI_UNSUPPORTED must be returned.  EFI_DEVICE_ERROR is returned if an error\r
  occurs attempting to retrieve the LowestSupportedVersion value for the\r
  currently stored firmware image.\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the LowestSupportedVersion value from the currently stored firmware\r
        image.\r
\r
  @param[out] LowestSupportedVersion  LowestSupportedVersion value retrieved\r
                                      from the currently stored firmware image.\r
\r
  @retval EFI_SUCCESS       The lowest supported version of currently stored\r
                            firmware image was returned in LowestSupportedVersion.\r
  @retval EFI_UNSUPPORTED   The firmware device does not support a method to\r
                            report the lowest supported version of the currently\r
                            stored firmware image.\r
  @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the lowest\r
                            supported version of the currently stored firmware\r
                            image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetLowestSupportedVersion (\r
  OUT UINT32  *LowestSupportedVersion\r
  );\r
\r
/**\r
  Returns the Null-terminated Unicode string that is used to fill in the\r
  VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is\r
  returned by the GetImageInfo() service of the Firmware Management Protocol.\r
  The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the VersionName string from the currently stored firmware image.\r
\r
  @param[out] VersionString  The version string retrieved from the currently\r
                             stored firmware image.\r
\r
  @retval EFI_SUCCESS            The version string of currently stored\r
                                 firmware image was returned in Version.\r
  @retval EFI_INVALID_PARAMETER  VersionString is NULL.\r
  @retval EFI_UNSUPPORTED        The firmware device does not support a method\r
                                 to report the version string of the currently\r
                                 stored firmware image.\r
  @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the\r
                                 version string of the currently stored\r
                                 firmware image.\r
  @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the\r
                                 buffer for the version string of the currently\r
                                 stored firmware image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetVersionString (\r
  OUT CHAR16  **VersionString\r
  );\r
\r
/**\r
  Returns the value used to fill in the Version field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then\r
  the firmware device supports a method to report the Version value from the\r
  currently stored firmware image.  If the value can not be reported for the\r
  firmware image currently stored in the firmware device, then EFI_UNSUPPORTED\r
  must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting\r
  to retrieve the LowestSupportedVersion value for the currently stored firmware\r
  image.\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the Version value from the currently stored firmware image.\r
\r
  @param[out] Version  The version value retrieved from the currently stored\r
                       firmware image.\r
\r
  @retval EFI_SUCCESS       The version of currently stored firmware image was\r
                            returned in Version.\r
  @retval EFI_UNSUPPORTED   The firmware device does not support a method to\r
                            report the version of the currently stored firmware\r
                            image.\r
  @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the version\r
                            of the currently stored firmware image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetVersion (\r
  OUT UINT32  *Version\r
  );\r
\r
/**\r
  Returns a copy of the firmware image currently stored in the firmware device.\r
\r
  @note It is recommended that all firmware devices support a method to retrieve\r
        a copy currently stored firmware image.  This can be used to support\r
        features such as recovery and rollback.\r
\r
  @param[out]     Image     Pointer to a caller allocated buffer where the\r
                            currently stored firmware image is copied to.\r
  @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.\r
                            On return, points to the size, in bytes, of firmware\r
                            image currently stored in the firmware device.\r
\r
  @retval EFI_SUCCESS            Image contains a copy of the firmware image\r
                                 currently stored in the firmware device, and\r
                                 ImageSize contains the size, in bytes, of the\r
                                 firmware image currently stored in the\r
                                 firmware device.\r
  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small\r
                                 to hold the firmware image currently stored in\r
                                 the firmware device. The buffer size required\r
                                 is returned in ImageSize.\r
  @retval EFI_INVALID_PARAMETER  The Image is NULL.\r
  @retval EFI_INVALID_PARAMETER  The ImageSize is NULL.\r
  @retval EFI_UNSUPPORTED        The operation is not supported.\r
  @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the\r
                                 firmware image currently stored in the firmware\r
                                 device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetImage (\r
  OUT    VOID   *Image,\r
  IN OUT UINTN  *ImageSize\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
\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
FmpDeviceCheckImage (\r
  IN  CONST VOID  *Image,\r
  IN  UINTN       ImageSize,\r
  OUT UINT32      *ImageUpdatable\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
\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
FmpDeviceSetImage (\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
  );\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
  firmware device must fail.\r
\r
  @note It is recommended that all firmware devices support a lock method to\r
        prevent modifications to a stored firmware image.\r
\r
  @note A firmware device lock mechanism is typically only cleared by a full\r
        system reset (not just sleep state/low power mode).\r
\r
  @retval  EFI_SUCCESS      The firmware device was locked.\r
  @retval  EFI_UNSUPPORTED  The firmware device does not support locking\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceLock (\r
  VOID\r
  );\r
\r
#endif\r