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