FmpDevicePkg/Include/Library/FmpDeviceLib.h

   1 /** @file
   2   Provides firmware device specific services to support updates of a firmware
   3   image stored in a firmware device.
   4
   5   Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>
   6   Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>
   7
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __FMP_DEVICE_LIB__
  13 #define __FMP_DEVICE_LIB__
  14
  15 #include <Protocol/FirmwareManagement.h>
  16
  17 /**
  18   Callback function that installs a Firmware Management Protocol instance onto
  19   a handle.
  20
  21   @param[in]  Handle  The device handle to install a Firmware Management
  22                       Protocol instance.
  23
  24   @retval  EFI_SUCCESS            A Firmware Management Protocol instance was
  25                                   installed onto Handle.
  26   @retval  EFI_INVALID_PARAMETER  Handle is invalid
  27   @retval  other                  A Firmware Management Protocol instance could
  28                                   not be installed onto Handle.
  29
  30 **/
  31 typedef
  32 EFI_STATUS
  33 (EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER)(
  34   IN  EFI_HANDLE      Handle
  35   );
  36
  37 /**
  38   Provide a function to install the Firmware Management Protocol instance onto a
  39   device handle when the device is managed by a driver that follows the UEFI
  40   Driver Model.  If the device is not managed by a driver that follows the UEFI
  41   Driver Model, then EFI_UNSUPPORTED is returned.
  42
  43   @param[in] FmpInstaller  Function that installs the Firmware Management
  44                            Protocol.
  45
  46   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  47                            UEFI Driver Model.  FmpInstaller must be called on
  48                            each Driver Binding Start().
  49   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  50                            the UEFI Driver Model.
  51   @retval other            The Firmware Management Protocol for this firmware
  52                            device is not installed.  The firmware device is
  53                            still locked using FmpDeviceLock().
  54
  55 **/
  56 EFI_STATUS
  57 EFIAPI
  58 RegisterFmpInstaller (
  59   IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER  FmpInstaller
  60   );
  61
  62 /**
  63   Returns the size, in bytes, of the firmware image currently stored in the
  64   firmware device.  This function is used to by the GetImage() and
  65   GetImageInfo() services of the Firmware Management Protocol.  If the image
  66   size can not be determined from the firmware device, then 0 must be returned.
  67
  68   @param[out] Size  Pointer to the size, in bytes, of the firmware image
  69                     currently stored in the firmware device.
  70
  71   @retval EFI_SUCCESS            The size of the firmware image currently
  72                                  stored in the firmware device was returned.
  73   @retval EFI_INVALID_PARAMETER  Size is NULL.
  74   @retval EFI_UNSUPPORTED        The firmware device does not support reporting
  75                                  the size of the currently stored firmware image.
  76   @retval EFI_DEVICE_ERROR       An error occured attempting to determine the
  77                                  size of the firmware image currently stored in
  78                                  in the firmware device.
  79
  80 **/
  81 EFI_STATUS
  82 EFIAPI
  83 FmpDeviceGetSize (
  84   OUT UINTN  *Size
  85   );
  86
  87 /**
  88   Returns the GUID value used to fill in the ImageTypeId field of the
  89   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
  90   service of the Firmware Management Protocol.  If EFI_UNSUPPORTED is returned,
  91   then the ImageTypeId field is set to gEfiCallerIdGuid.  If EFI_SUCCESS is
  92   returned, then ImageTypeId is set to the Guid returned from this function.
  93
  94   @param[out] Guid  Double pointer to a GUID value that is updated to point to
  95                     to a GUID value.  The GUID value is not allocated and must
  96                     not be modified or freed by the caller.
  97
  98   @retval EFI_SUCCESS      EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
  99                            to the returned Guid value.
 100   @retval EFI_UNSUPPORTED  EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
 101                            to gEfiCallerIdGuid.
 102
 103 **/
 104 EFI_STATUS
 105 EFIAPI
 106 FmpDeviceGetImageTypeIdGuidPtr (
 107   OUT EFI_GUID  **Guid
 108   );
 109
 110 /**
 111   Returns values used to fill in the AttributesSupported and AttributesSettings
 112   fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
 113   GetImageInfo() service of the Firmware Management Protocol.  The following
 114   bit values from the Firmware Management Protocol may be combined:
 115     IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
 116     IMAGE_ATTRIBUTE_RESET_REQUIRED
 117     IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
 118     IMAGE_ATTRIBUTE_IN_USE
 119     IMAGE_ATTRIBUTE_UEFI_IMAGE
 120
 121   @param[out] Supported  Attributes supported by this firmware device.
 122   @param[out] Setting    Attributes settings for this firmware device.
 123
 124   @retval EFI_SUCCESS            The attributes supported by the firmware
 125                                  device were returned.
 126   @retval EFI_INVALID_PARAMETER  Supported is NULL.
 127   @retval EFI_INVALID_PARAMETER  Setting is NULL.
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 FmpDeviceGetAttributes (
 133   OUT UINT64    *Supported,
 134   OUT UINT64    *Setting
 135   );
 136
 137 /**
 138   Returns the value used to fill in the LowestSupportedVersion field of the
 139   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 140   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 141   the firmware device supports a method to report the LowestSupportedVersion
 142   value from the currently stored firmware image.  If the value can not be
 143   reported for the firmware image currently stored in the firmware device, then
 144   EFI_UNSUPPORTED must be returned.  EFI_DEVICE_ERROR is returned if an error
 145   occurs attempting to retrieve the LowestSupportedVersion value for the
 146   currently stored firmware image.
 147
 148   @note It is recommended that all firmware devices support a method to report
 149         the LowestSupportedVersion value from the currently stored firmware
 150         image.
 151
 152   @param[out] LowestSupportedVersion  LowestSupportedVersion value retrieved
 153                                       from the currently stored firmware image.
 154
 155   @retval EFI_SUCCESS       The lowest supported version of currently stored
 156                             firmware image was returned in LowestSupportedVersion.
 157   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 158                             report the lowest supported version of the currently
 159                             stored firmware image.
 160   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the lowest
 161                             supported version of the currently stored firmware
 162                             image.
 163
 164 **/
 165 EFI_STATUS
 166 EFIAPI
 167 FmpDeviceGetLowestSupportedVersion (
 168   OUT UINT32  *LowestSupportedVersion
 169   );
 170
 171 /**
 172   Returns the Null-terminated Unicode string that is used to fill in the
 173   VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
 174   returned by the GetImageInfo() service of the Firmware Management Protocol.
 175   The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
 176
 177   @note It is recommended that all firmware devices support a method to report
 178         the VersionName string from the currently stored firmware image.
 179
 180   @param[out] VersionString  The version string retrieved from the currently
 181                              stored firmware image.
 182
 183   @retval EFI_SUCCESS            The version string of currently stored
 184                                  firmware image was returned in Version.
 185   @retval EFI_INVALID_PARAMETER  VersionString is NULL.
 186   @retval EFI_UNSUPPORTED        The firmware device does not support a method
 187                                  to report the version string of the currently
 188                                  stored firmware image.
 189   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 190                                  version string of the currently stored
 191                                  firmware image.
 192   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the
 193                                  buffer for the version string of the currently
 194                                  stored firmware image.
 195
 196 **/
 197 EFI_STATUS
 198 EFIAPI
 199 FmpDeviceGetVersionString (
 200   OUT CHAR16  **VersionString
 201   );
 202
 203 /**
 204   Returns the value used to fill in the Version field of the
 205   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 206   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 207   the firmware device supports a method to report the Version value from the
 208   currently stored firmware image.  If the value can not be reported for the
 209   firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
 210   must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting
 211   to retrieve the LowestSupportedVersion value for the currently stored firmware
 212   image.
 213
 214   @note It is recommended that all firmware devices support a method to report
 215         the Version value from the currently stored firmware image.
 216
 217   @param[out] Version  The version value retrieved from the currently stored
 218                        firmware image.
 219
 220   @retval EFI_SUCCESS       The version of currently stored firmware image was
 221                             returned in Version.
 222   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 223                             report the version of the currently stored firmware
 224                             image.
 225   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the version
 226                             of the currently stored firmware image.
 227
 228 **/
 229 EFI_STATUS
 230 EFIAPI
 231 FmpDeviceGetVersion (
 232   OUT UINT32  *Version
 233   );
 234
 235 /**
 236   Returns a copy of the firmware image currently stored in the firmware device.
 237
 238   @note It is recommended that all firmware devices support a method to retrieve
 239         a copy currently stored firmware image.  This can be used to support
 240         features such as recovery and rollback.
 241
 242   @param[out]     Image     Pointer to a caller allocated buffer where the
 243                             currently stored firmware image is copied to.
 244   @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
 245                             On return, points to the size, in bytes, of firmware
 246                             image currently stored in the firmware device.
 247
 248   @retval EFI_SUCCESS            Image contains a copy of the firmware image
 249                                  currently stored in the firmware device, and
 250                                  ImageSize contains the size, in bytes, of the
 251                                  firmware image currently stored in the
 252                                  firmware device.
 253   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small
 254                                  to hold the firmware image currently stored in
 255                                  the firmware device. The buffer size required
 256                                  is returned in ImageSize.
 257   @retval EFI_INVALID_PARAMETER  The Image is NULL.
 258   @retval EFI_INVALID_PARAMETER  The ImageSize is NULL.
 259   @retval EFI_UNSUPPORTED        The operation is not supported.
 260   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 261                                  firmware image currently stored in the firmware
 262                                  device.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 FmpDeviceGetImage (
 268   OUT    VOID   *Image,
 269   IN OUT UINTN  *ImageSize
 270   );
 271
 272 /**
 273   Checks if a new firmware image is valid for the firmware device.  This
 274   function allows firmware update operation to validate the firmware image
 275   before FmpDeviceSetImage() is called.
 276
 277   @param[in]  Image           Points to a new firmware image.
 278   @param[in]  ImageSize       Size, in bytes, of a new firmware image.
 279   @param[out] ImageUpdatable  Indicates if a new firmware image is valid for
 280                               a firmware update to the firmware device.  The
 281                               following values from the Firmware Management
 282                               Protocol are supported:
 283                                 IMAGE_UPDATABLE_VALID
 284                                 IMAGE_UPDATABLE_INVALID
 285                                 IMAGE_UPDATABLE_INVALID_TYPE
 286                                 IMAGE_UPDATABLE_INVALID_OLD
 287                                 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
 288
 289   @retval EFI_SUCCESS            The image was successfully checked.  Additional
 290                                  status information is returned in
 291                                  ImageUpdatable.
 292   @retval EFI_INVALID_PARAMETER  Image is NULL.
 293   @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.
 294
 295 **/
 296 EFI_STATUS
 297 EFIAPI
 298 FmpDeviceCheckImage (
 299   IN  CONST VOID  *Image,
 300   IN  UINTN       ImageSize,
 301   OUT UINT32      *ImageUpdatable
 302   );
 303
 304 /**
 305   Updates a firmware device with a new firmware image.  This function returns
 306   EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image
 307   is updatable, the function should perform the following minimal validations
 308   before proceeding to do the firmware image update.
 309     - Validate that the image is a supported image for this firmware device.
 310       Return EFI_ABORTED if the image is not supported.  Additional details
 311       on why the image is not a supported image may be returned in AbortReason.
 312     - Validate the data from VendorCode if is not NULL.  Firmware image
 313       validation must be performed before VendorCode data validation.
 314       VendorCode data is ignored or considered invalid if image validation
 315       fails.  Return EFI_ABORTED if the VendorCode data is invalid.
 316
 317   VendorCode enables vendor to implement vendor-specific firmware image update
 318   policy.  Null if the caller did not specify the policy or use the default
 319   policy.  As an example, vendor can implement a policy to allow an option to
 320   force a firmware image update when the abort reason is due to the new firmware
 321   image version is older than the current firmware image version or bad image
 322   checksum.  Sensitive operations such as those wiping the entire firmware image
 323   and render the device to be non-functional should be encoded in the image
 324   itself rather than passed with the VendorCode.  AbortReason enables vendor to
 325   have the option to provide a more detailed description of the abort reason to
 326   the caller.
 327
 328   @param[in]  Image             Points to the new firmware image.
 329   @param[in]  ImageSize         Size, in bytes, of the new firmware image.
 330   @param[in]  VendorCode        This enables vendor to implement vendor-specific
 331                                 firmware image update policy.  NULL indicates
 332                                 the caller did not specify the policy or use the
 333                                 default policy.
 334   @param[in]  Progress          A function used to report the progress of
 335                                 updating the firmware device with the new
 336                                 firmware image.
 337   @param[in]  CapsuleFwVersion  The version of the new firmware image from the
 338                                 update capsule that provided the new firmware
 339                                 image.
 340   @param[out] AbortReason       A pointer to a pointer to a Null-terminated
 341                                 Unicode string providing more details on an
 342                                 aborted operation. The buffer is allocated by
 343                                 this function with
 344                                 EFI_BOOT_SERVICES.AllocatePool().  It is the
 345                                 caller's responsibility to free this buffer with
 346                                 EFI_BOOT_SERVICES.FreePool().
 347
 348   @retval EFI_SUCCESS            The firmware device was successfully updated
 349                                  with the new firmware image.
 350   @retval EFI_ABORTED            The operation is aborted.  Additional details
 351                                  are provided in AbortReason.
 352   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 353   @retval EFI_UNSUPPORTED        The operation is not supported.
 354
 355 **/
 356 EFI_STATUS
 357 EFIAPI
 358 FmpDeviceSetImage (
 359   IN  CONST VOID                                     *Image,
 360   IN  UINTN                                          ImageSize,
 361   IN  CONST VOID                                     *VendorCode,       OPTIONAL
 362   IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL
 363   IN  UINT32                                         CapsuleFwVersion,
 364   OUT CHAR16                                         **AbortReason
 365   );
 366
 367 /**
 368   Lock the firmware device that contains a firmware image.  Once a firmware
 369   device is locked, any attempts to modify the firmware image contents in the
 370   firmware device must fail.
 371
 372   @note It is recommended that all firmware devices support a lock method to
 373         prevent modifications to a stored firmware image.
 374
 375   @note A firmware device lock mechanism is typically only cleared by a full
 376         system reset (not just sleep state/low power mode).
 377
 378   @retval  EFI_SUCCESS      The firmware device was locked.
 379   @retval  EFI_UNSUPPORTED  The firmware device does not support locking
 380
 381 **/
 382 EFI_STATUS
 383 EFIAPI
 384 FmpDeviceLock (
 385   VOID
 386   );
 387
 388 #endif