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