FmpDevicePkg/Include/Library/FmpDeviceLib.h

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