Vlv2TbltDevicePkg/Feature/Capsule/Library/FmpDeviceLibSample/FmpDeviceLib.c

   1 /**
   2
   3 Copyright (c) 2016, Microsoft Corporation
   4
   5 All rights reserved.
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10
  11 #include <PiDxe.h>
  12 #include <Library/DebugLib.h>
  13 #include <Protocol/FirmwareManagement.h>
  14 #include <Library/BaseLib.h>
  15 #include <Library/MemoryAllocationLib.h>
  16 #include <Library/BaseMemoryLib.h>
  17 #include <Library/FmpDeviceLib.h>
  18 #include <Library/UefiBootServicesTableLib.h>
  19
  20 /**
  21   Used to pass the FMP install function to this lib.
  22   This allows the library to have control of the handle
  23   that the FMP instance is installed on.  This allows the library
  24   to use DriverBinding protocol model to locate its device(s) in the
  25   system.
  26
  27   @param[in]  Function pointer to FMP install function.
  28
  29   @retval EFI_SUCCESS      Library has saved function pointer and will call function pointer on each DriverBinding Start.
  30   @retval EFI_UNSUPPORTED  Library doesn't use driver binding and only supports a single instance.
  31   @retval other error      Error occurred.  Don't install FMP
  32
  33 **/
  34 EFI_STATUS
  35 EFIAPI
  36 RegisterFmpInstaller(
  37 IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Func
  38 )
  39 {
  40   // Because this is a sample lib with very simple fake device we don't use
  41   // the driverbinding protocol to locate our device.
  42   //
  43   return EFI_UNSUPPORTED;
  44 }
  45
  46
  47 /**
  48 Used to get the size of the image in bytes.
  49 NOTE - Do not return zero as that will identify the device as
  50 not updatable.
  51
  52 @retval UINTN that represents the size of the firmware.
  53
  54 **/
  55 EFI_STATUS
  56 EFIAPI
  57 FmpDeviceGetSize (
  58   IN UINTN  *Size
  59   )
  60 {
  61   if (Size == NULL) {
  62     return EFI_INVALID_PARAMETER;
  63   }
  64   *Size = 0x1000;
  65   return EFI_SUCCESS;
  66 }
  67
  68 /**
  69 Used to return a library supplied guid that will be the ImageTypeId guid of the FMP descriptor.
  70 This is optional but can be used if at runtime the guid needs to be determined.
  71
  72 @param  Guid:  Double Guid Ptr that will be updated to point to guid.  This should be from static memory
  73 and will not be freed.
  74 @return EFI_UNSUPPORTED: if you library instance doesn't need dynamic guid return this.
  75 @return Error: Any error will cause the wrapper to use the GUID defined by PCD
  76 @return EFI_SUCCESS:  Guid ptr should be updated to point to static memeory which contains a valid guid
  77 **/
  78 EFI_STATUS
  79 EFIAPI
  80 FmpDeviceGetImageTypeIdGuidPtr(
  81   OUT EFI_GUID** Guid)
  82 {
  83   //this instance doesn't need dynamic guid detection.
  84   return EFI_UNSUPPORTED;
  85 }
  86
  87 /**
  88   Returns values used to fill in the AttributesSupported and AttributesSettings
  89   fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the
  90   GetImageInfo() service of the Firmware Management Protocol.  The following
  91   bit values from the Firmware Management Protocol may be combined:
  92     IMAGE_ATTRIBUTE_IMAGE_UPDATABLE
  93     IMAGE_ATTRIBUTE_RESET_REQUIRED
  94     IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED
  95     IMAGE_ATTRIBUTE_IN_USE
  96     IMAGE_ATTRIBUTE_UEFI_IMAGE
  97
  98   @param[out] Supported  Attributes supported by this firmware device.
  99   @param[out] Setting    Attributes settings for this firmware device.
 100
 101   @retval EFI_SUCCESS            The attributes supported by the firmware
 102                                  device were returned.
 103   @retval EFI_INVALID_PARAMETER  Supported is NULL.
 104   @retval EFI_INVALID_PARAMETER  Setting is NULL.
 105
 106 **/
 107 EFI_STATUS
 108 EFIAPI
 109 FmpDeviceGetAttributes (
 110   IN OUT UINT64  *Supported,
 111   IN OUT UINT64  *Setting
 112   )
 113 {
 114   if (Supported == NULL || Setting == NULL) {
 115     return EFI_INVALID_PARAMETER;
 116   }
 117   *Supported = (IMAGE_ATTRIBUTE_IMAGE_UPDATABLE | IMAGE_ATTRIBUTE_IN_USE);
 118   *Setting   = (IMAGE_ATTRIBUTE_IMAGE_UPDATABLE | IMAGE_ATTRIBUTE_IN_USE);
 119   return EFI_SUCCESS;
 120 }
 121
 122 /**
 123 Gets the current Lowest Supported Version.
 124 This is a protection mechanism so that a previous version with known issue is not
 125 applied.
 126
 127 ONLY implement this if your running firmware has a method to return this at runtime.
 128
 129 @param[out] Version           On return this value represents the
 130 current Lowest Supported Version (in same format as GetVersion).
 131
 132 @retval EFI_SUCCESS           The Lowest Supported Version was correctly retrieved
 133 @retval EFI_UNSUPPORTED       Device firmware doesn't support reporting LSV
 134 @retval EFI_DEVICE_ERROR      Error occurred when trying to get the LSV
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 FmpDeviceGetLowestSupportedVersion (
 139   IN OUT UINT32* LowestSupportedVersion
 140   )
 141 {
 142   return EFI_UNSUPPORTED;
 143 }
 144
 145
 146 /**
 147   Returns the Null-terminated Unicode string that is used to fill in the
 148   VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is
 149   returned by the GetImageInfo() service of the Firmware Management Protocol.
 150   The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().
 151
 152   @note It is recommended that all firmware devices support a method to report
 153         the VersionName string from the currently stored firmware image.
 154
 155   @param[out] VersionString  The version string retrieved from the currently
 156                              stored firmware image.
 157
 158   @retval EFI_SUCCESS            The version string of currently stored
 159                                  firmware image was returned in Version.
 160   @retval EFI_INVALID_PARAMETER  VersionString is NULL.
 161   @retval EFI_UNSUPPORTED        The firmware device does not support a method
 162                                  to report the version string of the currently
 163                                  stored firmware image.
 164   @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the
 165                                  version string of the currently stored
 166                                  firmware image.
 167   @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the
 168                                  buffer for the version string of the currently
 169                                  stored firmware image.
 170
 171 **/
 172 EFI_STATUS
 173 EFIAPI
 174 FmpDeviceGetVersionString (
 175   OUT CHAR16  **VersionString
 176   )
 177 {
 178   if (VersionString == NULL) {
 179     return EFI_INVALID_PARAMETER;
 180   }
 181   *VersionString = NULL;
 182   return EFI_UNSUPPORTED;
 183 }
 184
 185 /**
 186 Gets the current running version.
 187 ONLY implement this if your running firmware has a method to return this at runtime.
 188
 189 @param[out] Version           On return this value represents the current running version
 190
 191 @retval EFI_SUCCESS           The version was correctly retrieved
 192 @retval EFI_UNSUPPORTED       Device firmware doesn't support reporting current version
 193 @retval EFI_DEVICE_ERROR      Error occurred when trying to get the version
 194 **/
 195 EFI_STATUS
 196 EFIAPI
 197 FmpDeviceGetVersion(
 198 IN OUT UINT32* Version
 199 )
 200 {
 201   return EFI_UNSUPPORTED;
 202 }
 203
 204
 205 /**
 206 Retrieves a copy of the current firmware image of the device.
 207
 208 This function allows a copy of the current firmware image to be created and saved.
 209 The saved copy could later been used, for example, in firmware image recovery or rollback.
 210
 211 @param[out] Image              Points to the buffer where the current image is copied to.
 212 @param[out] ImageSize          On entry, points to the size of the buffer pointed to by Image, in bytes.
 213 On return, points to the length of the image, in bytes.
 214
 215 @retval EFI_SUCCESS            The device was successfully updated with the new image.
 216 @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to hold the
 217 image. The current buffer size needed to hold the image is returned
 218 in ImageSize.
 219 @retval EFI_INVALID_PARAMETER  The Image was NULL.
 220 @retval EFI_NOT_FOUND          The current image is not copied to the buffer.
 221 @retval EFI_UNSUPPORTED        The operation is not supported.
 222
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 FmpDeviceGetImage(
 227 IN  OUT  VOID                         *Image,
 228 IN  OUT  UINTN                        *ImageSize
 229 )
 230 /*++
 231
 232 Routine Description:
 233
 234     This is a function used to read the current firmware from the device into memory.
 235     This is an optional function and can return EFI_UNSUPPORTED.  This is useful for
 236     test and diagnostics.
 237
 238 Arguments:
 239     Image               -- Buffer to place the image into.
 240     ImageSize           -- Size of the Image buffer.
 241
 242 Return Value:
 243
 244     EFI_STATUS code.
 245     If not possible or not practical return EFI_UNSUPPORTED.
 246
 247 --*/
 248 {
 249   return EFI_UNSUPPORTED;
 250 }//GetImage()
 251
 252
 253 /**
 254 Updates the firmware image of the device.
 255
 256 This function updates the hardware with the new firmware image.
 257 This function returns EFI_UNSUPPORTED if the firmware image is not updatable.
 258 If the firmware image is updatable, the function should perform the following minimal validations
 259 before proceeding to do the firmware image update.
 260 - Validate the image is a supported image for this device.  The function returns EFI_ABORTED if
 261 the image is unsupported.  The function can optionally provide more detailed information on
 262 why the image is not a supported image.
 263 - Validate the data from VendorCode if not null.  Image validation must be performed before
 264 VendorCode data validation.  VendorCode data is ignored or considered invalid if image
 265 validation failed.  The function returns EFI_ABORTED if the data is invalid.
 266
 267 VendorCode enables vendor to implement vendor-specific firmware image update policy.  Null if
 268 the caller did not specify the policy or use the default policy.  As an example, vendor can implement
 269 a policy to allow an option to force a firmware image update when the abort reason is due to the new
 270 firmware image version is older than the current firmware image version or bad image checksum.
 271 Sensitive operations such as those wiping the entire firmware image and render the device to be
 272 non-functional should be encoded in the image itself rather than passed with the VendorCode.
 273 AbortReason enables vendor to have the option to provide a more detailed description of the abort
 274 reason to the caller.
 275
 276 @param[in]  Image              Points to the new image.
 277 @param[in]  ImageSize          Size of the new image in bytes.
 278 @param[in]  VendorCode         This enables vendor to implement vendor-specific firmware image update policy.
 279 Null indicates the caller did not specify the policy or use the default policy.
 280 @param[in]  Progress           A function used by the driver to report the progress of the firmware update.
 281 @param[in]  CapsuleFwVersion   FMP Payload Header version of the image
 282 @param[out] AbortReason        A pointer to a pointer to a null-terminated string providing more
 283 details for the aborted operation. The buffer is allocated by this function
 284 with AllocatePool(), and it is the caller's responsibility to free it with a
 285 call to FreePool().
 286
 287 @retval EFI_SUCCESS            The device was successfully updated with the new image.
 288 @retval EFI_ABORTED            The operation is aborted.
 289 @retval EFI_INVALID_PARAMETER  The Image was NULL.
 290 @retval EFI_UNSUPPORTED        The operation is not supported.
 291
 292 **/
 293 EFI_STATUS
 294 EFIAPI
 295 FmpDeviceSetImage (
 296 IN  CONST VOID                                       *Image,
 297 IN  UINTN                                            ImageSize,
 298 IN  CONST VOID                                       *VendorCode,
 299 IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS    Progress,
 300 IN  UINT32                                           CapsuleFwVersion,
 301 OUT CHAR16                                           **AbortReason
 302 )
 303 {
 304     EFI_STATUS Status                         = EFI_SUCCESS;
 305     UINT32 Updateable                         = 0;
 306
 307     Status = FmpDeviceCheckImage(Image, ImageSize, &Updateable);
 308     if (EFI_ERROR(Status))
 309     {
 310         DEBUG((DEBUG_ERROR, "SetImage - Check Image failed with %r.\n", Status));
 311         goto cleanup;
 312     }
 313
 314     if (Updateable != IMAGE_UPDATABLE_VALID)
 315     {
 316         DEBUG((DEBUG_ERROR, "SetImage - Check Image returned that the Image was not valid for update.  Updatable value = 0x%X.\n", Updateable));
 317         Status = EFI_ABORTED;
 318         goto cleanup;
 319     }
 320
 321     if (Progress == NULL)
 322     {
 323         DEBUG((DEBUG_ERROR, "SetImage - Invalid progress callback\n"));
 324         Status = EFI_INVALID_PARAMETER;
 325         goto cleanup;
 326     }
 327
 328     Status = Progress(15);
 329     if (EFI_ERROR(Status))
 330     {
 331         DEBUG((DEBUG_ERROR, "SetImage - Progress Callback failed with Status %r.\n", Status));
 332     }
 333
 334     {
 335       UINTN  p;
 336
 337       for (p = 20; p < 100; p++) {
 338         gBS->Stall (100000);  //us  = 0.1 seconds
 339         Progress (p);
 340       }
 341     }
 342
 343     //TODO: add support for VendorCode, and AbortReason
 344 cleanup:
 345     return Status;
 346 }// SetImage()
 347
 348
 349
 350 /**
 351 Checks if the firmware image is valid for the device.
 352
 353 This function allows firmware update application to validate the firmware image without
 354 invoking the SetImage() first.
 355
 356 @param[in]  Image              Points to the new image.
 357 @param[in]  ImageSize          Size of the new image in bytes.
 358 @param[out] ImageUpdatable     Indicates if the new image is valid for update. It also provides,
 359 if available, additional information if the image is invalid.
 360
 361 @retval EFI_SUCCESS            The image was successfully checked.
 362 @retval EFI_INVALID_PARAMETER  The Image was NULL.
 363
 364 **/
 365 EFI_STATUS
 366 EFIAPI
 367 FmpDeviceCheckImage(
 368 IN  CONST VOID                        *Image,
 369 IN  UINTN                             ImageSize,
 370 OUT UINT32                            *ImageUpdateable
 371 )
 372 {
 373     EFI_STATUS status = EFI_SUCCESS;
 374
 375     if (ImageUpdateable == NULL)
 376     {
 377         DEBUG((DEBUG_ERROR, "CheckImage - ImageUpdateable Pointer Parameter is NULL.\n"));
 378         status = EFI_INVALID_PARAMETER;
 379         goto cleanup;
 380     }
 381
 382     //
 383     //Set to valid and then if any tests fail it will update this flag.
 384     //
 385     *ImageUpdateable = IMAGE_UPDATABLE_VALID;
 386
 387     if (Image == NULL)
 388     {
 389         DEBUG((DEBUG_ERROR, "CheckImage - Image Pointer Parameter is NULL.\n"));
 390         *ImageUpdateable = IMAGE_UPDATABLE_INVALID; //not sure if this is needed
 391         return EFI_INVALID_PARAMETER;
 392     }
 393
 394 cleanup:
 395     return status;
 396 }// CheckImage()
 397
 398 /**
 399 Device firmware should trigger lock mechanism so that device fw can not be updated or tampered with.
 400 This lock mechanism is generally only cleared by a full system reset (not just sleep state/low power mode)
 401
 402 @retval EFI_SUCCESS           The device was successfully locked.
 403 @retval EFI_UNSUPPORTED       The hardware device/firmware doesn't support locking
 404
 405 **/
 406 EFI_STATUS
 407 EFIAPI
 408 FmpDeviceLock(
 409 )
 410 {
 411   return EFI_SUCCESS;
 412 }