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