FmpDevicePkg/Library/FmpDeviceLibNull/FmpDeviceLib.c

   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) Microsoft Corporation.<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 #include <PiDxe.h>
  13 #include <Guid/SystemResourceTable.h>
  14 #include <Library/FmpDeviceLib.h>
  15
  16 /**
  17   Provide a function to install the Firmware Management Protocol instance onto a
  18   device handle when the device is managed by a driver that follows the UEFI
  19   Driver Model.  If the device is not managed by a driver that follows the UEFI
  20   Driver Model, then EFI_UNSUPPORTED is returned.
  21
  22   @param[in] FmpInstaller  Function that installs the Firmware Management
  23                            Protocol.
  24
  25   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  26                            UEFI Driver Model.  FmpInstaller must be called on
  27                            each Driver Binding Start().
  28   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  29                            the UEFI Driver Model.
  30   @retval other            The Firmware Management Protocol for this firmware
  31                            device is not installed.  The firmware device is
  32                            still locked using FmpDeviceLock().
  33
  34 **/
  35 EFI_STATUS
  36 EFIAPI
  37 RegisterFmpInstaller (
  38   IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER  Function
  39   )
  40 {
  41   return EFI_UNSUPPORTED;
  42 }
  43
  44 /**
  45   Provide a function to uninstall the Firmware Management Protocol instance from a
  46   device handle when the device is managed by a driver that follows the UEFI
  47   Driver Model.  If the device is not managed by a driver that follows the UEFI
  48   Driver Model, then EFI_UNSUPPORTED is returned.
  49
  50   @param[in] FmpUninstaller  Function that installs the Firmware Management
  51                              Protocol.
  52
  53   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  54                            UEFI Driver Model.  FmpUninstaller must be called on
  55                            each Driver Binding Stop().
  56   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  57                            the UEFI Driver Model.
  58   @retval other            The Firmware Management Protocol for this firmware
  59                            device is not installed.  The firmware device is
  60                            still locked using FmpDeviceLock().
  61
  62 **/
  63 EFI_STATUS
  64 EFIAPI
  65 RegisterFmpUninstaller (
  66   IN FMP_DEVICE_LIB_REGISTER_FMP_UNINSTALLER  Function
  67   )
  68 {
  69   return EFI_UNSUPPORTED;
  70 }
  71
  72 /**
  73   Set the device context for the FmpDeviceLib services when the device is
  74   managed by a driver that follows the UEFI Driver Model.  If the device is not
  75   managed by a driver that follows the UEFI Driver Model, then EFI_UNSUPPORTED
  76   is returned.  Once a device context is set, the FmpDeviceLib services
  77   operate on the currently set device context.
  78
  79   @param[in]      Handle   Device handle for the FmpDeviceLib services.
  80                            If Handle is NULL, then Context is freed.
  81   @param[in, out] Context  Device context for the FmpDeviceLib services.
  82                            If Context is NULL, then a new context is allocated
  83                            for Handle and the current device context is set and
  84                            returned in Context.  If Context is not NULL, then
  85                            the current device context is set.
  86
  87   @retval EFI_SUCCESS      The device is managed by a driver that follows the
  88                            UEFI Driver Model.
  89   @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows
  90                            the UEFI Driver Model.
  91   @retval other            The Firmware Management Protocol for this firmware
  92                            device is not installed.  The firmware device is
  93                            still locked using FmpDeviceLock().
  94
  95 **/
  96 EFI_STATUS
  97 EFIAPI
  98 FmpDeviceSetContext (
  99   IN EFI_HANDLE  Handle,
 100   IN OUT VOID    **Context
 101   )
 102 {
 103   return EFI_UNSUPPORTED;
 104 }
 105
 106 /**
 107   Returns the size, in bytes, of the firmware image currently stored in the
 108   firmware device.  This function is used to by the GetImage() and
 109   GetImageInfo() services of the Firmware Management Protocol.  If the image
 110   size can not be determined from the firmware device, then 0 must be returned.
 111
 112   @param[out] Size  Pointer to the size, in bytes, of the firmware image
 113                     currently stored in the firmware device.
 114
 115   @retval EFI_SUCCESS            The size of the firmware image currently
 116                                  stored in the firmware device was returned.
 117   @retval EFI_INVALID_PARAMETER  Size is NULL.
 118   @retval EFI_UNSUPPORTED        The firmware device does not support reporting
 119                                  the size of the currently stored firmware image.
 120   @retval EFI_DEVICE_ERROR       An error occurred attempting to determine the
 121                                  size of the firmware image currently stored in
 122                                  in the firmware device.
 123
 124 **/
 125 EFI_STATUS
 126 EFIAPI
 127 FmpDeviceGetSize (
 128   OUT UINTN  *Size
 129   )
 130 {
 131   if (Size == NULL) {
 132     return EFI_INVALID_PARAMETER;
 133   }
 134   *Size = 0;
 135   return EFI_SUCCESS;
 136 }
 137
 138 /**
 139   Returns the GUID value used to fill in the ImageTypeId field of the
 140   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 141   service of the Firmware Management Protocol.  If EFI_UNSUPPORTED is returned,
 142   then the ImageTypeId field is set to gEfiCallerIdGuid.  If EFI_SUCCESS is
 143   returned, then ImageTypeId is set to the Guid returned from this function.
 144
 145   @param[out] Guid  Double pointer to a GUID value that is updated to point to
 146                     to a GUID value.  The GUID value is not allocated and must
 147                     not be modified or freed by the caller.
 148
 149   @retval EFI_SUCCESS      EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
 150                            to the returned Guid value.
 151   @retval EFI_UNSUPPORTED  EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set
 152                            to gEfiCallerIdGuid.
 153
 154 **/
 155 EFI_STATUS
 156 EFIAPI
 157 FmpDeviceGetImageTypeIdGuidPtr (
 158   OUT EFI_GUID  **Guid
 159   )
 160 {
 161   return EFI_UNSUPPORTED;
 162 }
 163
 164 /**
 165   Returns values used to fill in the AttributesSupported and AttributesSettings
 166   fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
 167   GetImageInfo() service of the Firmware Management Protocol.  The following
 168   bit values from the Firmware Management Protocol may be combined:
 169     IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
 170     IMAGE_ATTRIBUTE_RESET_REQUIRED
 171     IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
 172     IMAGE_ATTRIBUTE_IN_USE
 173     IMAGE_ATTRIBUTE_UEFI_IMAGE
 174
 175   @param[out] Supported  Attributes supported by this firmware device.
 176   @param[out] Setting    Attributes settings for this firmware device.
 177
 178   @retval EFI_SUCCESS            The attributes supported by the firmware
 179                                  device were returned.
 180   @retval EFI_INVALID_PARAMETER  Supported is NULL.
 181   @retval EFI_INVALID_PARAMETER  Setting is NULL.
 182
 183 **/
 184 EFI_STATUS
 185 EFIAPI
 186 FmpDeviceGetAttributes (
 187   OUT UINT64    *Supported,
 188   OUT UINT64    *Setting
 189   )
 190 {
 191   if (Supported == NULL || Setting == NULL) {
 192     return EFI_INVALID_PARAMETER;
 193   }
 194   *Supported = 0;
 195   *Setting   = 0;
 196   return EFI_SUCCESS;
 197 }
 198
 199 /**
 200   Returns the value used to fill in the LowestSupportedVersion field of the
 201   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 202   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 203   the firmware device supports a method to report the LowestSupportedVersion
 204   value from the currently stored firmware image.  If the value can not be
 205   reported for the firmware image currently stored in the firmware device, then
 206   EFI_UNSUPPORTED must be returned.  EFI_DEVICE_ERROR is returned if an error
 207   occurs attempting to retrieve the LowestSupportedVersion value for the
 208   currently stored firmware image.
 209
 210   @note It is recommended that all firmware devices support a method to report
 211         the LowestSupportedVersion value from the currently stored firmware
 212         image.
 213
 214   @param[out] LowestSupportedVersion  LowestSupportedVersion value retrieved
 215                                       from the currently stored firmware image.
 216
 217   @retval EFI_SUCCESS       The lowest supported version of currently stored
 218                             firmware image was returned in LowestSupportedVersion.
 219   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 220                             report the lowest supported version of the currently
 221                             stored firmware image.
 222   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the lowest
 223                             supported version of the currently stored firmware
 224                             image.
 225
 226 **/
 227 EFI_STATUS
 228 EFIAPI
 229 FmpDeviceGetLowestSupportedVersion (
 230   OUT UINT32  *LowestSupportedVersion
 231   )
 232 {
 233   return EFI_UNSUPPORTED;
 234 }
 235
 236 /**
 237   Returns the Null-terminated Unicode string that is used to fill in the
 238   VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
 239   returned by the GetImageInfo() service of the Firmware Management Protocol.
 240   The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
 241
 242   @note It is recommended that all firmware devices support a method to report
 243         the VersionName string from the currently stored firmware image.
 244
 245   @param[out] VersionString  The version string retrieved from the currently
 246                              stored firmware image.
 247
 248   @retval EFI_SUCCESS            The version string of currently stored
 249                                  firmware image was returned in Version.
 250   @retval EFI_INVALID_PARAMETER  VersionString is NULL.
 251   @retval EFI_UNSUPPORTED        The firmware device does not support a method
 252                                  to report the version string of the currently
 253                                  stored firmware image.
 254   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 255                                  version string of the currently stored
 256                                  firmware image.
 257   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the
 258                                  buffer for the version string of the currently
 259                                  stored firmware image.
 260
 261 **/
 262 EFI_STATUS
 263 EFIAPI
 264 FmpDeviceGetVersionString (
 265   OUT CHAR16  **VersionString
 266   )
 267 {
 268   if (VersionString == NULL) {
 269     return EFI_INVALID_PARAMETER;
 270   }
 271   *VersionString = NULL;
 272   return EFI_UNSUPPORTED;
 273 }
 274
 275 /**
 276   Returns the value used to fill in the Version field of the
 277   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 278   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 279   the firmware device supports a method to report the Version value from the
 280   currently stored firmware image.  If the value can not be reported for the
 281   firmware image currently stored in the firmware device, then EFI_UNSUPPORTED
 282   must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting
 283   to retrieve the LowestSupportedVersion value for the currently stored firmware
 284   image.
 285
 286   @note It is recommended that all firmware devices support a method to report
 287         the Version value from the currently stored firmware image.
 288
 289   @param[out] Version  The version value retrieved from the currently stored
 290                        firmware image.
 291
 292   @retval EFI_SUCCESS       The version of currently stored firmware image was
 293                             returned in Version.
 294   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 295                             report the version of the currently stored firmware
 296                             image.
 297   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the version
 298                             of the currently stored firmware image.
 299
 300 **/
 301 EFI_STATUS
 302 EFIAPI
 303 FmpDeviceGetVersion (
 304   OUT UINT32  *Version
 305   )
 306 {
 307   return EFI_UNSUPPORTED;
 308 }
 309
 310 /**
 311   Returns the value used to fill in the HardwareInstance field of the
 312   EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()
 313   service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then
 314   the firmware device supports a method to report the HardwareInstance value.
 315   If the value can not be reported for the firmware device, then EFI_UNSUPPORTED
 316   must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting
 317   to retrieve the HardwareInstance value for the firmware device.
 318
 319   @param[out] HardwareInstance  The hardware instance value for the firmware
 320                                 device.
 321
 322   @retval EFI_SUCCESS       The hardware instance for the current firmware
 323                             device is returned in HardwareInstance.
 324   @retval EFI_UNSUPPORTED   The firmware device does not support a method to
 325                             report the hardware instance value.
 326   @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the hardware
 327                             instance value.
 328
 329 **/
 330 EFI_STATUS
 331 EFIAPI
 332 FmpDeviceGetHardwareInstance (
 333   OUT UINT64  *HardwareInstance
 334   )
 335 {
 336   return EFI_UNSUPPORTED;
 337 }
 338
 339 /**
 340   Returns a copy of the firmware image currently stored in the firmware device.
 341
 342   @note It is recommended that all firmware devices support a method to retrieve
 343         a copy currently stored firmware image.  This can be used to support
 344         features such as recovery and rollback.
 345
 346   @param[out]     Image     Pointer to a caller allocated buffer where the
 347                             currently stored firmware image is copied to.
 348   @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.
 349                             On return, points to the size, in bytes, of firmware
 350                             image currently stored in the firmware device.
 351
 352   @retval EFI_SUCCESS            Image contains a copy of the firmware image
 353                                  currently stored in the firmware device, and
 354                                  ImageSize contains the size, in bytes, of the
 355                                  firmware image currently stored in the
 356                                  firmware device.
 357   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small
 358                                  to hold the firmware image currently stored in
 359                                  the firmware device. The buffer size required
 360                                  is returned in ImageSize.
 361   @retval EFI_INVALID_PARAMETER  The Image is NULL.
 362   @retval EFI_INVALID_PARAMETER  The ImageSize is NULL.
 363   @retval EFI_UNSUPPORTED        The operation is not supported.
 364   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 365                                  firmware image currently stored in the firmware
 366                                  device.
 367
 368 **/
 369 EFI_STATUS
 370 EFIAPI
 371 FmpDeviceGetImage (
 372   OUT    VOID   *Image,
 373   IN OUT UINTN  *ImageSize
 374   )
 375 {
 376   return EFI_UNSUPPORTED;
 377 }
 378
 379 /**
 380   Checks if a new firmware image is valid for the firmware device.  This
 381   function allows firmware update operation to validate the firmware image
 382   before FmpDeviceSetImage() is called.
 383
 384   @param[in]  Image           Points to a new firmware image.
 385   @param[in]  ImageSize       Size, in bytes, of a new firmware image.
 386   @param[out] ImageUpdatable  Indicates if a new firmware image is valid for
 387                               a firmware update to the firmware device.  The
 388                               following values from the Firmware Management
 389                               Protocol are supported:
 390                                 IMAGE_UPDATABLE_VALID
 391                                 IMAGE_UPDATABLE_INVALID
 392                                 IMAGE_UPDATABLE_INVALID_TYPE
 393                                 IMAGE_UPDATABLE_INVALID_OLD
 394                                 IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
 395
 396   @retval EFI_SUCCESS            The image was successfully checked.  Additional
 397                                  status information is returned in
 398                                  ImageUpdatable.
 399   @retval EFI_INVALID_PARAMETER  Image is NULL.
 400   @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.
 401
 402 **/
 403 EFI_STATUS
 404 EFIAPI
 405 FmpDeviceCheckImage (
 406   IN  CONST VOID  *Image,
 407   IN  UINTN       ImageSize,
 408   OUT UINT32      *ImageUpdatable
 409   )
 410 {
 411   UINT32  LastAttemptStatus;
 412
 413   return FmpDeviceCheckImageWithStatus (Image, ImageSize, ImageUpdatable, &LastAttemptStatus);
 414 }
 415
 416 /**
 417   Checks if a new firmware image is valid for the firmware device.  This
 418   function allows firmware update operation to validate the firmware image
 419   before FmpDeviceSetImage() is called.
 420
 421   @param[in]  Image               Points to a new firmware image.
 422   @param[in]  ImageSize           Size, in bytes, of a new firmware image.
 423   @param[out] ImageUpdatable      Indicates if a new firmware image is valid for
 424                                   a firmware update to the firmware device.  The
 425                                   following values from the Firmware Management
 426                                   Protocol are supported:
 427                                     IMAGE_UPDATABLE_VALID
 428                                     IMAGE_UPDATABLE_INVALID
 429                                     IMAGE_UPDATABLE_INVALID_TYPE
 430                                     IMAGE_UPDATABLE_INVALID_OLD
 431                                     IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE
 432   @param[out] LastAttemptStatus   A pointer to a UINT32 that holds the last attempt
 433                                   status to report back to the ESRT table in case
 434                                   of error. This value will only be checked when this
 435                                   function returns an error.
 436
 437                                   The return status code must fall in the range of
 438                                   LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
 439                                   LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
 440
 441                                   If the value falls outside this range, it will be converted
 442                                   to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
 443
 444   @retval EFI_SUCCESS            The image was successfully checked.  Additional
 445                                  status information is returned in
 446                                  ImageUpdatable.
 447   @retval EFI_INVALID_PARAMETER  Image is NULL.
 448   @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.
 449
 450 **/
 451 EFI_STATUS
 452 EFIAPI
 453 FmpDeviceCheckImageWithStatus (
 454   IN  CONST VOID  *Image,
 455   IN  UINTN       ImageSize,
 456   OUT UINT32      *ImageUpdatable,
 457   OUT UINT32      *LastAttemptStatus
 458   )
 459 {
 460   *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;
 461
 462   return EFI_SUCCESS;
 463 }
 464
 465 /**
 466   Updates a firmware device with a new firmware image.  This function returns
 467   EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image
 468   is updatable, the function should perform the following minimal validations
 469   before proceeding to do the firmware image update.
 470     - Validate that the image is a supported image for this firmware device.
 471       Return EFI_ABORTED if the image is not supported.  Additional details
 472       on why the image is not a supported image may be returned in AbortReason.
 473     - Validate the data from VendorCode if is not NULL.  Firmware image
 474       validation must be performed before VendorCode data validation.
 475       VendorCode data is ignored or considered invalid if image validation
 476       fails.  Return EFI_ABORTED if the VendorCode data is invalid.
 477
 478   VendorCode enables vendor to implement vendor-specific firmware image update
 479   policy.  Null if the caller did not specify the policy or use the default
 480   policy.  As an example, vendor can implement a policy to allow an option to
 481   force a firmware image update when the abort reason is due to the new firmware
 482   image version is older than the current firmware image version or bad image
 483   checksum.  Sensitive operations such as those wiping the entire firmware image
 484   and render the device to be non-functional should be encoded in the image
 485   itself rather than passed with the VendorCode.  AbortReason enables vendor to
 486   have the option to provide a more detailed description of the abort reason to
 487   the caller.
 488
 489   @param[in]  Image             Points to the new firmware image.
 490   @param[in]  ImageSize         Size, in bytes, of the new firmware image.
 491   @param[in]  VendorCode        This enables vendor to implement vendor-specific
 492                                 firmware image update policy.  NULL indicates
 493                                 the caller did not specify the policy or use the
 494                                 default policy.
 495   @param[in]  Progress          A function used to report the progress of
 496                                 updating the firmware device with the new
 497                                 firmware image.
 498   @param[in]  CapsuleFwVersion  The version of the new firmware image from the
 499                                 update capsule that provided the new firmware
 500                                 image.
 501   @param[out] AbortReason       A pointer to a pointer to a Null-terminated
 502                                 Unicode string providing more details on an
 503                                 aborted operation. The buffer is allocated by
 504                                 this function with
 505                                 EFI_BOOT_SERVICES.AllocatePool().  It is the
 506                                 caller's responsibility to free this buffer with
 507                                 EFI_BOOT_SERVICES.FreePool().
 508
 509   @retval EFI_SUCCESS            The firmware device was successfully updated
 510                                  with the new firmware image.
 511   @retval EFI_ABORTED            The operation is aborted.  Additional details
 512                                  are provided in AbortReason.
 513   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 514   @retval EFI_UNSUPPORTED        The operation is not supported.
 515
 516 **/
 517 EFI_STATUS
 518 EFIAPI
 519 FmpDeviceSetImage (
 520   IN  CONST VOID                                     *Image,
 521   IN  UINTN                                          ImageSize,
 522   IN  CONST VOID                                     *VendorCode,       OPTIONAL
 523   IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL
 524   IN  UINT32                                         CapsuleFwVersion,
 525   OUT CHAR16                                         **AbortReason
 526   )
 527 {
 528   UINT32  LastAttemptStatus;
 529
 530   return  FmpDeviceSetImageWithStatus (
 531             Image,
 532             ImageSize,
 533             VendorCode,
 534             Progress,
 535             CapsuleFwVersion,
 536             AbortReason,
 537             &LastAttemptStatus
 538             );
 539 }
 540
 541 /**
 542   Updates a firmware device with a new firmware image.  This function returns
 543   EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image
 544   is updatable, the function should perform the following minimal validations
 545   before proceeding to do the firmware image update.
 546     - Validate that the image is a supported image for this firmware device.
 547       Return EFI_ABORTED if the image is not supported.  Additional details
 548       on why the image is not a supported image may be returned in AbortReason.
 549     - Validate the data from VendorCode if is not NULL.  Firmware image
 550       validation must be performed before VendorCode data validation.
 551       VendorCode data is ignored or considered invalid if image validation
 552       fails.  Return EFI_ABORTED if the VendorCode data is invalid.
 553
 554   VendorCode enables vendor to implement vendor-specific firmware image update
 555   policy.  Null if the caller did not specify the policy or use the default
 556   policy.  As an example, vendor can implement a policy to allow an option to
 557   force a firmware image update when the abort reason is due to the new firmware
 558   image version is older than the current firmware image version or bad image
 559   checksum.  Sensitive operations such as those wiping the entire firmware image
 560   and render the device to be non-functional should be encoded in the image
 561   itself rather than passed with the VendorCode.  AbortReason enables vendor to
 562   have the option to provide a more detailed description of the abort reason to
 563   the caller.
 564
 565   @param[in]  Image             Points to the new firmware image.
 566   @param[in]  ImageSize         Size, in bytes, of the new firmware image.
 567   @param[in]  VendorCode        This enables vendor to implement vendor-specific
 568                                 firmware image update policy.  NULL indicates
 569                                 the caller did not specify the policy or use the
 570                                 default policy.
 571   @param[in]  Progress          A function used to report the progress of
 572                                 updating the firmware device with the new
 573                                 firmware image.
 574   @param[in]  CapsuleFwVersion  The version of the new firmware image from the
 575                                 update capsule that provided the new firmware
 576                                 image.
 577   @param[out] AbortReason       A pointer to a pointer to a Null-terminated
 578                                 Unicode string providing more details on an
 579                                 aborted operation. The buffer is allocated by
 580                                 this function with
 581                                 EFI_BOOT_SERVICES.AllocatePool().  It is the
 582                                 caller's responsibility to free this buffer with
 583                                 EFI_BOOT_SERVICES.FreePool().
 584   @param[out] LastAttemptStatus A pointer to a UINT32 that holds the last attempt
 585                                 status to report back to the ESRT table in case
 586                                 of error. This value will only be checked when this
 587                                 function returns an error.
 588
 589                                 The return status code must fall in the range of
 590                                 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MIN_ERROR_CODE_VALUE to
 591                                 LAST_ATTEMPT_STATUS_DEVICE_LIBRARY_MAX_ERROR_CODE_VALUE.
 592
 593                                 If the value falls outside this range, it will be converted
 594                                 to LAST_ATTEMPT_STATUS_ERROR_UNSUCCESSFUL.
 595
 596   @retval EFI_SUCCESS            The firmware device was successfully updated
 597                                  with the new firmware image.
 598   @retval EFI_ABORTED            The operation is aborted.  Additional details
 599                                  are provided in AbortReason.
 600   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 601   @retval EFI_UNSUPPORTED        The operation is not supported.
 602
 603 **/
 604 EFI_STATUS
 605 EFIAPI
 606 FmpDeviceSetImageWithStatus (
 607   IN  CONST VOID                                     *Image,
 608   IN  UINTN                                          ImageSize,
 609   IN  CONST VOID                                     *VendorCode,       OPTIONAL
 610   IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL
 611   IN  UINT32                                         CapsuleFwVersion,
 612   OUT CHAR16                                         **AbortReason,
 613   OUT UINT32                                         *LastAttemptStatus
 614   )
 615 {
 616   *LastAttemptStatus = LAST_ATTEMPT_STATUS_SUCCESS;
 617
 618   return EFI_UNSUPPORTED;
 619 }
 620
 621 /**
 622   Lock the firmware device that contains a firmware image.  Once a firmware
 623   device is locked, any attempts to modify the firmware image contents in the
 624   firmware device must fail.
 625
 626   @note It is recommended that all firmware devices support a lock method to
 627         prevent modifications to a stored firmware image.
 628
 629   @note A firmware device lock mechanism is typically only cleared by a full
 630         system reset (not just sleep state/low power mode).
 631
 632   @retval  EFI_SUCCESS      The firmware device was locked.
 633   @retval  EFI_UNSUPPORTED  The firmware device does not support locking
 634
 635 **/
 636 EFI_STATUS
 637 EFIAPI
 638 FmpDeviceLock (
 639   VOID
 640   )
 641 {
 642   return EFI_UNSUPPORTED;
 643 }