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