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

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