UefiCpuPkg/Feature/Capsule/MicrocodeUpdateDxe/MicrocodeUpdate.h

   1 /** @file
   2   Microcode update header file.
   3
   4   Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13 **/
  14
  15 #ifndef _MICROCODE_FMP_H_
  16 #define _MICROCODE_FMP_H_
  17
  18 #include <PiDxe.h>
  19
  20 #include <Guid/SystemResourceTable.h>
  21 #include <Guid/MicrocodeFmp.h>
  22
  23 #include <Protocol/FirmwareManagement.h>
  24
  25 #include <Library/BaseLib.h>
  26 #include <Library/BaseMemoryLib.h>
  27 #include <Library/DebugLib.h>
  28 #include <Library/MemoryAllocationLib.h>
  29 #include <Library/PcdLib.h>
  30 #include <Library/UefiBootServicesTableLib.h>
  31 #include <Library/UefiLib.h>
  32 #include <Library/UefiRuntimeServicesTableLib.h>
  33 #include <Library/UefiDriverEntryPoint.h>
  34 #include <Library/DevicePathLib.h>
  35 #include <Library/HobLib.h>
  36 #include <Library/MicrocodeFlashAccessLib.h>
  37
  38 #include <Register/Cpuid.h>
  39 #include <Register/Msr.h>
  40 #include <Register/Microcode.h>
  41
  42 #define MICROCODE_FMP_PRIVATE_DATA_SIGNATURE  SIGNATURE_32('M', 'C', 'U', 'F')
  43
  44 //
  45 // Microcode FMP private data structure.
  46 //
  47
  48 typedef struct {
  49   UINT32 LastAttemptVersion;
  50   UINT32 LastAttemptStatus;
  51 } MICROCODE_FMP_LAST_ATTEMPT_VARIABLE;
  52
  53 struct _MICROCODE_FMP_PRIVATE_DATA {
  54   UINT32                               Signature;
  55   EFI_FIRMWARE_MANAGEMENT_PROTOCOL     Fmp;
  56   EFI_HANDLE                           Handle;
  57   UINT8                                DescriptorCount;
  58   EFI_FIRMWARE_IMAGE_DESCRIPTOR        *ImageDescriptor;
  59   UINT32                               PackageVersion;
  60   CHAR16                               *PackageVersionName;
  61   MICROCODE_FMP_LAST_ATTEMPT_VARIABLE  LastAttempt;
  62 };
  63
  64 typedef struct _MICROCODE_FMP_PRIVATE_DATA  MICROCODE_FMP_PRIVATE_DATA;
  65
  66 #define MICROCODE_FMP_LAST_ATTEMPT_VARIABLE_NAME  L"MicrocodeLastAttempVar"
  67
  68 /**
  69   Returns a pointer to the MICROCODE_FMP_PRIVATE_DATA structure from the input a as Fmp.
  70
  71   If the signatures matches, then a pointer to the data structure that contains
  72   a specified field of that data structure is returned.
  73
  74   @param  a              Pointer to the field specified by ServiceBinding within
  75                          a data structure of type MICROCODE_FMP_PRIVATE_DATA.
  76
  77 **/
  78 #define MICROCODE_FMP_PRIVATE_DATA_FROM_FMP(a) \
  79   CR ( \
  80   (a), \
  81   MICROCODE_FMP_PRIVATE_DATA, \
  82   Fmp, \
  83   MICROCODE_FMP_PRIVATE_DATA_SIGNATURE \
  84   )
  85
  86 /**
  87   Get current Microcode information.
  88
  89   @param[out]  ImageDescriptor  Microcode ImageDescriptor
  90   @param[in]   DescriptorCount  The count of Microcode ImageDescriptor allocated.
  91
  92   @return Microcode count
  93 **/
  94 UINTN
  95 GetMicrocodeInfo (
  96   OUT EFI_FIRMWARE_IMAGE_DESCRIPTOR  *ImageDescriptor, OPTIONAL
  97   IN  UINTN                          DescriptorCount   OPTIONAL
  98   );
  99
 100 /**
 101   Read Microcode.
 102
 103   @param[in]       ImageIndex The index of Microcode image.
 104   @param[in, out]  Image      The Microcode image buffer.
 105   @param[in, out]  ImageSize  The size of Microcode image buffer in bytes.
 106
 107   @retval EFI_SUCCESS    The Microcode image is read.
 108   @retval EFI_NOT_FOUND  The Microcode image is not found.
 109 **/
 110 EFI_STATUS
 111 MicrocodeRead (
 112   IN UINTN      ImageIndex,
 113   IN OUT VOID   *Image,
 114   IN OUT UINTN  *ImageSize
 115   );
 116
 117 /**
 118   Write Microcode.
 119
 120   @param[in]   ImageIndex         The index of Microcode image.
 121   @param[in]   Image              The Microcode image buffer.
 122   @param[in]   ImageSize          The size of Microcode image buffer in bytes.
 123   @param[out]  LastAttemptVersion The last attempt version, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 124   @param[out]  LastAttemptStatus  The last attempt status, which will be recorded in ESRT and FMP EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 125   @param[out]  AbortReason        A pointer to a pointer to a null-terminated string providing more
 126                                   details for the aborted operation. The buffer is allocated by this function
 127                                   with AllocatePool(), and it is the caller's responsibility to free it with a
 128                                   call to FreePool().
 129
 130   @retval EFI_SUCCESS               The Microcode image is written.
 131   @retval EFI_VOLUME_CORRUPTED      The Microcode image is corrupt.
 132   @retval EFI_INCOMPATIBLE_VERSION  The Microcode image version is incorrect.
 133   @retval EFI_SECURITY_VIOLATION    The Microcode image fails to load.
 134   @retval EFI_WRITE_PROTECTED   The flash device is read only.
 135 **/
 136 EFI_STATUS
 137 MicrocodeWrite (
 138   IN UINTN    ImageIndex,
 139   IN VOID     *Image,
 140   IN UINTN    ImageSize,
 141   OUT UINT32  *LastAttemptVersion,
 142   OUT UINT32  *LastAttemptStatus,
 143   OUT CHAR16  **AbortReason
 144   );
 145
 146 /**
 147   Returns information about the current firmware image(s) of the device.
 148
 149   This function allows a copy of the current firmware image to be created and saved.
 150   The saved copy could later been used, for example, in firmware image recovery or rollback.
 151
 152   @param[in]      This               A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 153   @param[in, out] ImageInfoSize      A pointer to the size, in bytes, of the ImageInfo buffer.
 154                                      On input, this is the size of the buffer allocated by the caller.
 155                                      On output, it is the size of the buffer returned by the firmware
 156                                      if the buffer was large enough, or the size of the buffer needed
 157                                      to contain the image(s) information if the buffer was too small.
 158   @param[in, out] ImageInfo          A pointer to the buffer in which firmware places the current image(s)
 159                                      information. The information is an array of EFI_FIRMWARE_IMAGE_DESCRIPTORs.
 160   @param[out]     DescriptorVersion  A pointer to the location in which firmware returns the version number
 161                                      associated with the EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 162   @param[out]     DescriptorCount    A pointer to the location in which firmware returns the number of
 163                                      descriptors or firmware images within this device.
 164   @param[out]     DescriptorSize     A pointer to the location in which firmware returns the size, in bytes,
 165                                      of an individual EFI_FIRMWARE_IMAGE_DESCRIPTOR.
 166   @param[out]     PackageVersion     A version number that represents all the firmware images in the device.
 167                                      The format is vendor specific and new version must have a greater value
 168                                      than the old version. If PackageVersion is not supported, the value is
 169                                      0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version comparison
 170                                      is to be performed using PackageVersionName. A value of 0xFFFFFFFD indicates
 171                                      that package version update is in progress.
 172   @param[out]     PackageVersionName A pointer to a pointer to a null-terminated string representing the
 173                                      package version name. The buffer is allocated by this function with
 174                                      AllocatePool(), and it is the caller's responsibility to free it with a call
 175                                      to FreePool().
 176
 177   @retval EFI_SUCCESS                The device was successfully updated with the new image.
 178   @retval EFI_BUFFER_TOO_SMALL       The ImageInfo buffer was too small. The current buffer size
 179                                      needed to hold the image(s) information is returned in ImageInfoSize.
 180   @retval EFI_INVALID_PARAMETER      ImageInfoSize is NULL.
 181   @retval EFI_DEVICE_ERROR           Valid information could not be returned. Possible corrupted image.
 182
 183 **/
 184 EFI_STATUS
 185 EFIAPI
 186 FmpGetImageInfo (
 187   IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL       *This,
 188   IN OUT    UINTN                           *ImageInfoSize,
 189   IN OUT    EFI_FIRMWARE_IMAGE_DESCRIPTOR   *ImageInfo,
 190   OUT       UINT32                          *DescriptorVersion,
 191   OUT       UINT8                           *DescriptorCount,
 192   OUT       UINTN                           *DescriptorSize,
 193   OUT       UINT32                          *PackageVersion,
 194   OUT       CHAR16                          **PackageVersionName
 195   );
 196
 197 /**
 198   Retrieves a copy of the current firmware image of the device.
 199
 200   This function allows a copy of the current firmware image to be created and saved.
 201   The saved copy could later been used, for example, in firmware image recovery or rollback.
 202
 203   @param[in]     This            A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 204   @param[in]     ImageIndex      A unique number identifying the firmware image(s) within the device.
 205                                  The number is between 1 and DescriptorCount.
 206   @param[in,out] Image           Points to the buffer where the current image is copied to.
 207   @param[in,out] ImageSize       On entry, points to the size of the buffer pointed to by Image, in bytes.
 208                                  On return, points to the length of the image, in bytes.
 209
 210   @retval EFI_SUCCESS            The device was successfully updated with the new image.
 211   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to hold the
 212                                  image. The current buffer size needed to hold the image is returned
 213                                  in ImageSize.
 214   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 215   @retval EFI_NOT_FOUND          The current image is not copied to the buffer.
 216   @retval EFI_UNSUPPORTED        The operation is not supported.
 217   @retval EFI_SECURITY_VIOLATIO  The operation could not be performed due to an authentication failure.
 218
 219 **/
 220 EFI_STATUS
 221 EFIAPI
 222 FmpGetImage (
 223   IN  EFI_FIRMWARE_MANAGEMENT_PROTOCOL  *This,
 224   IN  UINT8                             ImageIndex,
 225   IN  OUT  VOID                         *Image,
 226   IN  OUT  UINTN                        *ImageSize
 227   );
 228
 229 /**
 230   Updates the firmware image of the device.
 231
 232   This function updates the hardware with the new firmware image.
 233   This function returns EFI_UNSUPPORTED if the firmware image is not updatable.
 234   If the firmware image is updatable, the function should perform the following minimal validations
 235   before proceeding to do the firmware image update.
 236   - Validate the image authentication if image has attribute
 237     IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED. The function returns
 238     EFI_SECURITY_VIOLATION if the validation fails.
 239   - Validate the image is a supported image for this device. The function returns EFI_ABORTED if
 240     the image is unsupported. The function can optionally provide more detailed information on
 241     why the image is not a supported image.
 242   - Validate the data from VendorCode if not null. Image validation must be performed before
 243     VendorCode data validation. VendorCode data is ignored or considered invalid if image
 244     validation failed. The function returns EFI_ABORTED if the data is invalid.
 245
 246   VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if
 247   the caller did not specify the policy or use the default policy. As an example, vendor can implement
 248   a policy to allow an option to force a firmware image update when the abort reason is due to the new
 249   firmware image version is older than the current firmware image version or bad image checksum.
 250   Sensitive operations such as those wiping the entire firmware image and render the device to be
 251   non-functional should be encoded in the image itself rather than passed with the VendorCode.
 252   AbortReason enables vendor to have the option to provide a more detailed description of the abort
 253   reason to the caller.
 254
 255   @param[in]  This               A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 256   @param[in]  ImageIndex         A unique number identifying the firmware image(s) within the device.
 257                                  The number is between 1 and DescriptorCount.
 258   @param[in]  Image              Points to the new image.
 259   @param[in]  ImageSize          Size of the new image in bytes.
 260   @param[in]  VendorCode         This enables vendor to implement vendor-specific firmware image update policy.
 261                                  Null indicates the caller did not specify the policy or use the default policy.
 262   @param[in]  Progress           A function used by the driver to report the progress of the firmware update.
 263   @param[out] AbortReason        A pointer to a pointer to a null-terminated string providing more
 264                                  details for the aborted operation. The buffer is allocated by this function
 265                                  with AllocatePool(), and it is the caller's responsibility to free it with a
 266                                  call to FreePool().
 267
 268   @retval EFI_SUCCESS            The device was successfully updated with the new image.
 269   @retval EFI_ABORTED            The operation is aborted.
 270   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 271   @retval EFI_UNSUPPORTED        The operation is not supported.
 272   @retval EFI_SECURITY_VIOLATIO  The operation could not be performed due to an authentication failure.
 273
 274 **/
 275 EFI_STATUS
 276 EFIAPI
 277 FmpSetImage (
 278   IN  EFI_FIRMWARE_MANAGEMENT_PROTOCOL                 *This,
 279   IN  UINT8                                            ImageIndex,
 280   IN  CONST VOID                                       *Image,
 281   IN  UINTN                                            ImageSize,
 282   IN  CONST VOID                                       *VendorCode,
 283   IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS    Progress,
 284   OUT CHAR16                                           **AbortReason
 285   );
 286
 287 /**
 288   Checks if the firmware image is valid for the device.
 289
 290   This function allows firmware update application to validate the firmware image without
 291   invoking the SetImage() first.
 292
 293   @param[in]  This               A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 294   @param[in]  ImageIndex         A unique number identifying the firmware image(s) within the device.
 295                                  The number is between 1 and DescriptorCount.
 296   @param[in]  Image              Points to the new image.
 297   @param[in]  ImageSize          Size of the new image in bytes.
 298   @param[out] ImageUpdatable     Indicates if the new image is valid for update. It also provides,
 299                                  if available, additional information if the image is invalid.
 300
 301   @retval EFI_SUCCESS            The image was successfully checked.
 302   @retval EFI_INVALID_PARAMETER  The Image was NULL.
 303   @retval EFI_UNSUPPORTED        The operation is not supported.
 304   @retval EFI_SECURITY_VIOLATIO  The operation could not be performed due to an authentication failure.
 305
 306 **/
 307 EFI_STATUS
 308 EFIAPI
 309 FmpCheckImage (
 310   IN  EFI_FIRMWARE_MANAGEMENT_PROTOCOL  *This,
 311   IN  UINT8                             ImageIndex,
 312   IN  CONST VOID                        *Image,
 313   IN  UINTN                             ImageSize,
 314   OUT UINT32                            *ImageUpdatable
 315   );
 316
 317 /**
 318   Returns information about the firmware package.
 319
 320   This function returns package information.
 321
 322   @param[in]  This                     A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 323   @param[out] PackageVersion           A version number that represents all the firmware images in the device.
 324                                        The format is vendor specific and new version must have a greater value
 325                                        than the old version. If PackageVersion is not supported, the value is
 326                                        0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version
 327                                        comparison is to be performed using PackageVersionName. A value of
 328                                        0xFFFFFFFD indicates that package version update is in progress.
 329   @param[out] PackageVersionName       A pointer to a pointer to a null-terminated string representing
 330                                        the package version name. The buffer is allocated by this function with
 331                                        AllocatePool(), and it is the caller's responsibility to free it with a
 332                                        call to FreePool().
 333   @param[out] PackageVersionNameMaxLen The maximum length of package version name if device supports update of
 334                                        package version name. A value of 0 indicates the device does not support
 335                                        update of package version name. Length is the number of Unicode characters,
 336                                        including the terminating null character.
 337   @param[out] AttributesSupported      Package attributes that are supported by this device. See 'Package Attribute
 338                                        Definitions' for possible returned values of this parameter. A value of 1
 339                                        indicates the attribute is supported and the current setting value is
 340                                        indicated in AttributesSetting. A value of 0 indicates the attribute is not
 341                                        supported and the current setting value in AttributesSetting is meaningless.
 342   @param[out] AttributesSetting        Package attributes. See 'Package Attribute Definitions' for possible returned
 343                                        values of this parameter
 344
 345   @retval EFI_SUCCESS                  The package information was successfully returned.
 346   @retval EFI_UNSUPPORTED              The operation is not supported.
 347
 348 **/
 349 EFI_STATUS
 350 EFIAPI
 351 FmpGetPackageInfo (
 352   IN  EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
 353   OUT UINT32                           *PackageVersion,
 354   OUT CHAR16                           **PackageVersionName,
 355   OUT UINT32                           *PackageVersionNameMaxLen,
 356   OUT UINT64                           *AttributesSupported,
 357   OUT UINT64                           *AttributesSetting
 358   );
 359
 360 /**
 361   Updates information about the firmware package.
 362
 363   This function updates package information.
 364   This function returns EFI_UNSUPPORTED if the package information is not updatable.
 365   VendorCode enables vendor to implement vendor-specific package information update policy.
 366   Null if the caller did not specify this policy or use the default policy.
 367
 368   @param[in]  This               A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
 369   @param[in]  Image              Points to the authentication image.
 370                                  Null if authentication is not required.
 371   @param[in]  ImageSize          Size of the authentication image in bytes.
 372                                  0 if authentication is not required.
 373   @param[in]  VendorCode         This enables vendor to implement vendor-specific firmware
 374                                  image update policy.
 375                                  Null indicates the caller did not specify this policy or use
 376                                  the default policy.
 377   @param[in]  PackageVersion     The new package version.
 378   @param[in]  PackageVersionName A pointer to the new null-terminated Unicode string representing
 379                                  the package version name.
 380                                  The string length is equal to or less than the value returned in
 381                                  PackageVersionNameMaxLen.
 382
 383   @retval EFI_SUCCESS            The device was successfully updated with the new package
 384                                  information.
 385   @retval EFI_INVALID_PARAMETER  The PackageVersionName length is longer than the value
 386                                  returned in PackageVersionNameMaxLen.
 387   @retval EFI_UNSUPPORTED        The operation is not supported.
 388   @retval EFI_SECURITY_VIOLATIO  The operation could not be performed due to an authentication failure.
 389
 390 **/
 391 EFI_STATUS
 392 EFIAPI
 393 FmpSetPackageInfo (
 394   IN  EFI_FIRMWARE_MANAGEMENT_PROTOCOL   *This,
 395   IN  CONST VOID                         *Image,
 396   IN  UINTN                              ImageSize,
 397   IN  CONST VOID                         *VendorCode,
 398   IN  UINT32                             PackageVersion,
 399   IN  CONST CHAR16                       *PackageVersionName
 400   );
 401
 402 #endif
 403