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 - 2019, 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   Callback function that uninstalls a Firmware Management Protocol instance from
  39   a handle.
  40
  41   @param[in]  Handle  The device handle to uninstall a Firmware Management
  42                       Protocol instance.
  43
  44   @retval  EFI_SUCCESS            A Firmware Management Protocol instance was
  45                                   uninstalled from Handle.
  46   @retval  EFI_INVALID_PARAMETER  Handle is invalid
  47   @retval  other                  A Firmware Management Protocol instance could
  48                                   not be uninstalled from Handle.
  49
  50 **/
  51 typedef
  52 EFI_STATUS
  53 (EFIAPI *FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER)(
  54   IN  EFI_HANDLE      Handle
  55   );
  56
  57 /**
  58   Provide a function to install the Firmware Management Protocol instance onto a
  59   device handle when the device is managed by a driver that follows the UEFI
  60   Driver Model.  If the device is not managed by a driver that follows the UEFI
  61   Driver Model, then EFI_UNSUPPORTED is returned.
  62
  63   @param[in] FmpInstaller  Function that installs the Firmware Management
  64                            Protocol.
  65
  66   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  67                            UEFI Driver Model.  FmpInstaller must be called on
  68                            each Driver Binding Start().
  69   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  70                            the UEFI Driver Model.
  71   @retval other            The Firmware Management Protocol for this firmware
  72                            device is not installed.  The firmware device is
  73                            still locked using FmpDeviceLock().
  74
  75 **/
  76 EFI_STATUS
  77 EFIAPI
  78 RegisterFmpInstaller (
  79   IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER  FmpInstaller
  80   );
  81
  82 /**
  83   Provide a function to uninstall the Firmware Management Protocol instance from a
  84   device handle when the device is managed by a driver that follows the UEFI
  85   Driver Model.  If the device is not managed by a driver that follows the UEFI
  86   Driver Model, then EFI_UNSUPPORTED is returned.
  87
  88   @param[in] FmpUninstaller  Function that installs the Firmware Management
  89                              Protocol.
  90
  91   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  92                            UEFI Driver Model.  FmpUninstaller must be called on
  93                            each Driver Binding Stop().
  94   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  95                            the UEFI Driver Model.
  96   @retval other            The Firmware Management Protocol for this firmware
  97                            device is not installed.  The firmware device is
  98                            still locked using FmpDeviceLock().
  99
 100 **/
 101 EFI_STATUS
 102 EFIAPI
 103 RegisterFmpUninstaller (
 104   IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER  FmpUninstaller
 105   );
 106
 107 /**
 108   Set the device context for the FmpDeviceLib services when the device is
 109   managed by a driver that follows the UEFI Driver Model.  If the device is not
 110   managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
 111   is returned.  Once a device context is set, the FmpDeviceLib services
 112   operate on the currently set device context.
 113
 114   @param[in]      Handle   Device handle for the FmpDeviceLib services.
 115                            If Handle is NULL, then Context is freed.
 116   @param[in, out] Context  Device context for the FmpDeviceLib services.
 117                            If Context is NULL, then a new context is allocated
 118                            for Handle and the current device context is set and
 119                            returned in Context.  If Context is not NULL, then
 120                            the current device context is set.
 121
 122   @retval EFI_SUCCESS      The device is managed by a driver that follows the
 123                            UEFI Driver Model.
 124   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
 125                            the UEFI Driver Model.
 126   @retval other            The Firmware Management Protocol for this firmware
 127                            device is not installed.  The firmware device is
 128                            still locked using FmpDeviceLock().
 129
 130 **/
 131 EFI_STATUS
 132 EFIAPI
 133 FmpDeviceSetContext (
 134   IN EFI_HANDLE  Handle,
 135   IN OUT VOID    **Context
 136   );
 137
 138 /**
 139   Returns the size, in bytes, of the firmware image currently stored in the
 140   firmware device.  This function is used to by the GetImage() and
 141   GetImageInfo() services of the Firmware Management Protocol.  If the image
 142   size can not be determined from the firmware device, then 0 must be returned.
 143
 144   @param[out] Size  Pointer to the size, in bytes, of the firmware image
 145                     currently stored in the firmware device.
 146
 147   @retval EFI_SUCCESS            The size of the firmware image currently
 148                                  stored in the firmware device was returned.
 149   @retval EFI_INVALID_PARAMETER  Size is NULL.
 150   @retval EFI_UNSUPPORTED        The firmware device does not support reporting
 151                                  the size of the currently stored firmware image.
 152   @retval EFI_DEVICE_ERROR       An error occurred attempting to determine the
 153                                  size of the firmware image currently stored in
 154                                  in the firmware device.
 155
 156 **/
 157 EFI_STATUS
 158 EFIAPI
 159 FmpDeviceGetSize (
 160   OUT UINTN  *Size
 161   );
 162
 163 /**
 164   Returns the GUID value used to fill in the ImageTypeId field of the
 165   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 166   service of the Firmware Management Protocol.  If EFI_UNSUPPORTED is returned,
 167   then the ImageTypeId field is set to gEfiCallerIdGuid.  If EFI_SUCCESS is
 168   returned, then ImageTypeId is set to the Guid returned from this function.
 169
 170   @param[out] Guid  Double pointer to a GUID value that is updated to point to
 171                     to a GUID value.  The GUID value is not allocated and must
 172                     not be modified or freed by the caller.
 173
 174   @retval EFI_SUCCESS      EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
 175                            to the returned Guid value.
 176   @retval EFI_UNSUPPORTED  EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
 177                            to gEfiCallerIdGuid.
 178
 179 **/
 180 EFI_STATUS
 181 EFIAPI
 182 FmpDeviceGetImageTypeIdGuidPtr (
 183   OUT EFI_GUID  **Guid
 184   );
 185
 186 /**
 187   Returns values used to fill in the AttributesSupported and AttributesSettings
 188   fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
 189   GetImageInfo() service of the Firmware Management Protocol.  The following
 190   bit values from the Firmware Management Protocol may be combined:
 191     IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
 192     IMAGE_ATTRIBUTE_RESET_REQUIRED
 193     IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
 194     IMAGE_ATTRIBUTE_IN_USE
 195     IMAGE_ATTRIBUTE_UEFI_IMAGE
 196
 197   @param[out] Supported  Attributes supported by this firmware device.
 198   @param[out] Setting    Attributes settings for this firmware device.
 199
 200   @retval EFI_SUCCESS            The attributes supported by the firmware
 201                                  device were returned.
 202   @retval EFI_INVALID_PARAMETER  Supported is NULL.
 203   @retval EFI_INVALID_PARAMETER  Setting is NULL.
 204
 205 **/
 206 EFI_STATUS
 207 EFIAPI
 208 FmpDeviceGetAttributes (
 209   OUT UINT64    *Supported,
 210   OUT UINT64    *Setting
 211   );
 212
 213 /**
 214   Returns the value used to fill in the LowestSupportedVersion field of the
 215   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 216   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 217   the firmware device supports a method to report the LowestSupportedVersion
 218   value from the currently stored firmware image.  If the value can not be
 219   reported for the firmware image currently stored in the firmware device, then
 220   EFI_UNSUPPORTED must be returned.  EFI_DEVICE_ERROR is returned if an error
 221   occurs attempting to retrieve the LowestSupportedVersion value for the
 222   currently stored firmware image.
 223
 224   @note It is recommended that all firmware devices support a method to report
 225         the LowestSupportedVersion value from the currently stored firmware
 226         image.
 227
 228   @param[out] LowestSupportedVersion  LowestSupportedVersion value retrieved
 229                                       from the currently stored firmware image.
 230
 231   @retval EFI_SUCCESS       The lowest supported version of currently stored
 232                             firmware image was returned in LowestSupportedVersion.
 233   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 234                             report the lowest supported version of the currently
 235                             stored firmware image.
 236   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the lowest
 237                             supported version of the currently stored firmware
 238                             image.
 239
 240 **/
 241 EFI_STATUS
 242 EFIAPI
 243 FmpDeviceGetLowestSupportedVersion (
 244   OUT UINT32  *LowestSupportedVersion
 245   );
 246
 247 /**
 248   Returns the Null-terminated Unicode string that is used to fill in the
 249   VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
 250   returned by the GetImageInfo() service of the Firmware Management Protocol.
 251   The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
 252
 253   @note It is recommended that all firmware devices support a method to report
 254         the VersionName string from the currently stored firmware image.
 255
 256   @param[out] VersionString  The version string retrieved from the currently
 257                              stored firmware image.
 258
 259   @retval EFI_SUCCESS            The version string of currently stored
 260                                  firmware image was returned in Version.
 261   @retval EFI_INVALID_PARAMETER  VersionString is NULL.
 262   @retval EFI_UNSUPPORTED        The firmware device does not support a method
 263                                  to report the version string of the currently
 264                                  stored firmware image.
 265   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 266                                  version string of the currently stored
 267                                  firmware image.
 268   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the
 269                                  buffer for the version string of the currently
 270                                  stored firmware image.
 271
 272 **/
 273 EFI_STATUS
 274 EFIAPI
 275 FmpDeviceGetVersionString (
 276   OUT CHAR16  **VersionString
 277   );
 278
 279 /**
 280   Returns the value used to fill in the Version field of the
 281   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 282   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 283   the firmware device supports a method to report the Version value from the
 284   currently stored firmware image.  If the value can not be reported for the
 285   firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
 286   must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting
 287   to retrieve the LowestSupportedVersion value for the currently stored firmware
 288   image.
 289
 290   @note It is recommended that all firmware devices support a method to report
 291         the Version value from the currently stored firmware image.
 292
 293   @param[out] Version  The version value retrieved from the currently stored
 294                        firmware image.
 295
 296   @retval EFI_SUCCESS       The version of currently stored firmware image was
 297                             returned in Version.
 298   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 299                             report the version of the currently stored firmware
 300                             image.
 301   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the version
 302                             of the currently stored firmware image.
 303
 304 **/
 305 EFI_STATUS
 306 EFIAPI
 307 FmpDeviceGetVersion (
 308   OUT UINT32  *Version
 309   );
 310
 311 /**
 312   Returns the value used to fill in the HardwareInstance field of the
 313   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 314   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 315   the firmware device supports a method to report the HardwareInstance value.
 316   If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
 317   must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting
 318   to retrieve the HardwareInstance value for the firmware device.
 319
 320   @param[out] HardwareInstance  The hardware instance value for the firmware
 321                                 device.
 322
 323   @retval EFI_SUCCESS       The hardware instance for the current firmware
 324                             device is returned in HardwareInstance.
 325   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 326                             report the hardware instance value.
 327   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the hardware
 328                             instance value.
 329
 330 **/
 331 EFI_STATUS
 332 EFIAPI
 333 FmpDeviceGetHardwareInstance (
 334   OUT UINT64  *HardwareInstance
 335   );
 336
 337 /**
 338   Returns a copy of the firmware image currently stored in the firmware device.
 339
 340   @note It is recommended that all firmware devices support a method to retrieve
 341         a copy currently stored firmware image.  This can be used to support
 342         features such as recovery and rollback.
 343
 344   @param[out]     Image     Pointer to a caller allocated buffer where the
 345                             currently stored firmware image is copied to.
 346   @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
 347                             On return, points to the size, in bytes, of firmware
 348                             image currently stored in the firmware device.
 349
 350   @retval EFI_SUCCESS            Image contains a copy of the firmware image
 351                                  currently stored in the firmware device, and
 352                                  ImageSize contains the size, in bytes, of the
 353                                  firmware image currently stored in the
 354                                  firmware device.
 355   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small
 356                                  to hold the firmware image currently stored in
 357                                  the firmware device. The buffer size required
 358                                  is returned in ImageSize.
 359   @retval EFI_INVALID_PARAMETER  The Image is NULL.
 360   @retval EFI_INVALID_PARAMETER  The ImageSize is NULL.
 361   @retval EFI_UNSUPPORTED        The operation is not supported.
 362   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 363                                  firmware image currently stored in the firmware
 364                                  device.
 365
 366 **/
 367 EFI_STATUS
 368 EFIAPI
 369 FmpDeviceGetImage (
 370   OUT    VOID   *Image,
 371   IN OUT UINTN  *ImageSize
 372   );
 373
 374 /**
 375   Checks if a new firmware image is valid for the firmware device.  This
 376   function allows firmware update operation to validate the firmware image
 377   before FmpDeviceSetImage() is called.
 378
 379   @param[in]  Image           Points to a new firmware image.
 380   @param[in]  ImageSize       Size, in bytes, of a new firmware image.
 381   @param[out] ImageUpdatable  Indicates if a new firmware image is valid for
 382                               a firmware update to the firmware device.  The
 383                               following values from the Firmware Management
 384                               Protocol are supported:
 385                                 IMAGE_UPDATABLE_VALID
 386                                 IMAGE_UPDATABLE_INVALID
 387                                 IMAGE_UPDATABLE_INVALID_TYPE
 388                                 IMAGE_UPDATABLE_INVALID_OLD
 389                                 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
 390
 391   @retval EFI_SUCCESS            The image was successfully checked.  Additional
 392                                  status information is returned in
 393                                  ImageUpdatable.
 394   @retval EFI_INVALID_PARAMETER  Image is NULL.
 395   @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.
 396
 397 **/
 398 EFI_STATUS
 399 EFIAPI
 400 FmpDeviceCheckImage (
 401   IN  CONST VOID  *Image,
 402   IN  UINTN       ImageSize,
 403   OUT UINT32      *ImageUpdatable
 404   );
 405
 406 /**
 407   Updates a firmware device with a new firmware image.  This function returns
 408   EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image
 409   is updatable, the function should perform the following minimal validations
 410   before proceeding to do the firmware image update.
 411     - Validate that the image is a supported image for this firmware device.
 412       Return EFI_ABORTED if the image is not supported.  Additional details
 413       on why the image is not a supported image may be returned in AbortReason.
 414     - Validate the data from VendorCode if is not NULL.  Firmware image
 415       validation must be performed before VendorCode data validation.
 416       VendorCode data is ignored or considered invalid if image validation
 417       fails.  Return EFI_ABORTED if the VendorCode data is invalid.
 418
 419   VendorCode enables vendor to implement vendor-specific firmware image update
 420   policy.  Null if the caller did not specify the policy or use the default
 421   policy.  As an example, vendor can implement a policy to allow an option to
 422   force a firmware image update when the abort reason is due to the new firmware
 423   image version is older than the current firmware image version or bad image
 424   checksum.  Sensitive operations such as those wiping the entire firmware image
 425   and render the device to be non-functional should be encoded in the image
 426   itself rather than passed with the VendorCode.  AbortReason enables vendor to
 427   have the option to provide a more detailed description of the abort reason to
 428   the caller.
 429
 430   @param[in]  Image             Points to the new firmware image.
 431   @param[in]  ImageSize         Size, in bytes, of the new firmware image.
 432   @param[in]  VendorCode        This enables vendor to implement vendor-specific
 433                                 firmware image update policy.  NULL indicates
 434                                 the caller did not specify the policy or use the
 435                                 default policy.
 436   @param[in]  Progress          A function used to report the progress of
 437                                 updating the firmware device with the new
 438                                 firmware image.
 439   @param[in]  CapsuleFwVersion  The version of the new firmware image from the
 440                                 update capsule that provided the new firmware
 441                                 image.
 442   @param[out] AbortReason       A pointer to a pointer to a Null-terminated
 443                                 Unicode string providing more details on an
 444                                 aborted operation. The buffer is allocated by
 445                                 this function with
 446                                 EFI_BOOT_SERVICES.AllocatePool().  It is the
 447                                 caller's responsibility to free this buffer with
 448                                 EFI_BOOT_SERVICES.FreePool().
 449
 450   @retval EFI_SUCCESS            The firmware device was successfully updated
 451                                  with the new firmware image.
 452   @retval EFI_ABORTED            The operation is aborted.  Additional details
 453                                  are provided in AbortReason.
 454   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 455   @retval EFI_UNSUPPORTED        The operation is not supported.
 456
 457 **/
 458 EFI_STATUS
 459 EFIAPI
 460 FmpDeviceSetImage (
 461   IN  CONST VOID                                     *Image,
 462   IN  UINTN                                          ImageSize,
 463   IN  CONST VOID                                     *VendorCode,       OPTIONAL
 464   IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL
 465   IN  UINT32                                         CapsuleFwVersion,
 466   OUT CHAR16                                         **AbortReason
 467   );
 468
 469 /**
 470   Lock the firmware device that contains a firmware image.  Once a firmware
 471   device is locked, any attempts to modify the firmware image contents in the
 472   firmware device must fail.
 473
 474   @note It is recommended that all firmware devices support a lock method to
 475         prevent modifications to a stored firmware image.
 476
 477   @note A firmware device lock mechanism is typically only cleared by a full
 478         system reset (not just sleep state/low power mode).
 479
 480   @retval  EFI_SUCCESS      The firmware device was locked.
 481   @retval  EFI_UNSUPPORTED  The firmware device does not support locking
 482
 483 **/
 484 EFI_STATUS
 485 EFIAPI
 486 FmpDeviceLock (
 487   VOID
 488   );
 489
 490 #endif