SignedCapsulePkg/Universal/SystemFirmwareUpdate/SystemFirmwareDxe.h

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