MdePkg/Include/Pi/PiFirmwareFile.h

   1 /** @file
   2   The firmware file related definitions in PI.
   3
   4 Copyright (c) 2006 - 2017, Intel Corporation. All rights reserved.<BR>
   5 SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8   PI Version 1.6.
   9
  10 **/
  11
  12 #ifndef __PI_FIRMWARE_FILE_H__
  13 #define __PI_FIRMWARE_FILE_H__
  14
  15 #pragma pack(1)
  16 ///
  17 /// Used to verify the integrity of the file.
  18 ///
  19 typedef union {
  20   struct {
  21     ///
  22     /// The IntegrityCheck.Checksum.Header field is an 8-bit checksum of the file
  23     /// header. The State and IntegrityCheck.Checksum.File fields are assumed
  24     /// to be zero and the checksum is calculated such that the entire header sums to zero.
  25     ///
  26     UINT8    Header;
  27     ///
  28     /// If the FFS_ATTRIB_CHECKSUM (see definition below) bit of the Attributes
  29     /// field is set to one, the IntegrityCheck.Checksum.File field is an 8-bit
  30     /// checksum of the file data.
  31     /// If the FFS_ATTRIB_CHECKSUM bit of the Attributes field is cleared to zero,
  32     /// the IntegrityCheck.Checksum.File field must be initialized with a value of
  33     /// 0xAA. The IntegrityCheck.Checksum.File field is valid any time the
  34     /// EFI_FILE_DATA_VALID bit is set in the State field.
  35     ///
  36     UINT8    File;
  37   } Checksum;
  38   ///
  39   /// This is the full 16 bits of the IntegrityCheck field.
  40   ///
  41   UINT16    Checksum16;
  42 } EFI_FFS_INTEGRITY_CHECK;
  43
  44 ///
  45 /// FFS_FIXED_CHECKSUM is the checksum value used when the
  46 /// FFS_ATTRIB_CHECKSUM attribute bit is clear.
  47 ///
  48 #define FFS_FIXED_CHECKSUM  0xAA
  49
  50 typedef UINT8  EFI_FV_FILETYPE;
  51 typedef UINT8  EFI_FFS_FILE_ATTRIBUTES;
  52 typedef UINT8  EFI_FFS_FILE_STATE;
  53
  54 ///
  55 /// File Types Definitions
  56 ///
  57 #define EFI_FV_FILETYPE_ALL                    0x00
  58 #define EFI_FV_FILETYPE_RAW                    0x01
  59 #define EFI_FV_FILETYPE_FREEFORM               0x02
  60 #define EFI_FV_FILETYPE_SECURITY_CORE          0x03
  61 #define EFI_FV_FILETYPE_PEI_CORE               0x04
  62 #define EFI_FV_FILETYPE_DXE_CORE               0x05
  63 #define EFI_FV_FILETYPE_PEIM                   0x06
  64 #define EFI_FV_FILETYPE_DRIVER                 0x07
  65 #define EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER   0x08
  66 #define EFI_FV_FILETYPE_APPLICATION            0x09
  67 #define EFI_FV_FILETYPE_MM                     0x0A
  68 #define EFI_FV_FILETYPE_SMM                    EFI_FV_FILETYPE_MM
  69 #define EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE  0x0B
  70 #define EFI_FV_FILETYPE_COMBINED_MM_DXE        0x0C
  71 #define EFI_FV_FILETYPE_COMBINED_SMM_DXE       EFI_FV_FILETYPE_COMBINED_MM_DXE
  72 #define EFI_FV_FILETYPE_MM_CORE                0x0D
  73 #define EFI_FV_FILETYPE_SMM_CORE               EFI_FV_FILETYPE_MM_CORE
  74 #define EFI_FV_FILETYPE_MM_STANDALONE          0x0E
  75 #define EFI_FV_FILETYPE_MM_CORE_STANDALONE     0x0F
  76 #define EFI_FV_FILETYPE_OEM_MIN                0xc0
  77 #define EFI_FV_FILETYPE_OEM_MAX                0xdf
  78 #define EFI_FV_FILETYPE_DEBUG_MIN              0xe0
  79 #define EFI_FV_FILETYPE_DEBUG_MAX              0xef
  80 #define EFI_FV_FILETYPE_FFS_MIN                0xf0
  81 #define EFI_FV_FILETYPE_FFS_MAX                0xff
  82 #define EFI_FV_FILETYPE_FFS_PAD                0xf0
  83 ///
  84 /// FFS File Attributes.
  85 ///
  86 #define FFS_ATTRIB_LARGE_FILE        0x01
  87 #define FFS_ATTRIB_DATA_ALIGNMENT_2  0x02
  88 #define FFS_ATTRIB_FIXED             0x04
  89 #define FFS_ATTRIB_DATA_ALIGNMENT    0x38
  90 #define FFS_ATTRIB_CHECKSUM          0x40
  91
  92 ///
  93 /// FFS File State Bits.
  94 ///
  95 #define EFI_FILE_HEADER_CONSTRUCTION  0x01
  96 #define EFI_FILE_HEADER_VALID         0x02
  97 #define EFI_FILE_DATA_VALID           0x04
  98 #define EFI_FILE_MARKED_FOR_UPDATE    0x08
  99 #define EFI_FILE_DELETED              0x10
 100 #define EFI_FILE_HEADER_INVALID       0x20
 101
 102 ///
 103 /// Each file begins with the header that describe the
 104 /// contents and state of the files.
 105 ///
 106 typedef struct {
 107   ///
 108   /// This GUID is the file name. It is used to uniquely identify the file.
 109   ///
 110   EFI_GUID                   Name;
 111   ///
 112   /// Used to verify the integrity of the file.
 113   ///
 114   EFI_FFS_INTEGRITY_CHECK    IntegrityCheck;
 115   ///
 116   /// Identifies the type of file.
 117   ///
 118   EFI_FV_FILETYPE            Type;
 119   ///
 120   /// Declares various file attribute bits.
 121   ///
 122   EFI_FFS_FILE_ATTRIBUTES    Attributes;
 123   ///
 124   /// The length of the file in bytes, including the FFS header.
 125   ///
 126   UINT8                      Size[3];
 127   ///
 128   /// Used to track the state of the file throughout the life of the file from creation to deletion.
 129   ///
 130   EFI_FFS_FILE_STATE         State;
 131 } EFI_FFS_FILE_HEADER;
 132
 133 typedef struct {
 134   ///
 135   /// This GUID is the file name. It is used to uniquely identify the file. There may be only
 136   /// one instance of a file with the file name GUID of Name in any given firmware
 137   /// volume, except if the file type is EFI_FV_FILETYPE_FFS_PAD.
 138   ///
 139   EFI_GUID                   Name;
 140
 141   ///
 142   /// Used to verify the integrity of the file.
 143   ///
 144   EFI_FFS_INTEGRITY_CHECK    IntegrityCheck;
 145
 146   ///
 147   /// Identifies the type of file.
 148   ///
 149   EFI_FV_FILETYPE            Type;
 150
 151   ///
 152   /// Declares various file attribute bits.
 153   ///
 154   EFI_FFS_FILE_ATTRIBUTES    Attributes;
 155
 156   ///
 157   /// The length of the file in bytes, including the FFS header.
 158   /// The length of the file data is either (Size - sizeof(EFI_FFS_FILE_HEADER)). This calculation means a
 159   /// zero-length file has a Size of 24 bytes, which is sizeof(EFI_FFS_FILE_HEADER).
 160   /// Size is not required to be a multiple of 8 bytes. Given a file F, the next file header is
 161   /// located at the next 8-byte aligned firmware volume offset following the last byte of the file F.
 162   ///
 163   UINT8                 Size[3];
 164
 165   ///
 166   /// Used to track the state of the file throughout the life of the file from creation to deletion.
 167   ///
 168   EFI_FFS_FILE_STATE    State;
 169
 170   ///
 171   /// If FFS_ATTRIB_LARGE_FILE is set in Attributes, then ExtendedSize exists and Size must be set to zero.
 172   /// If FFS_ATTRIB_LARGE_FILE is not set then EFI_FFS_FILE_HEADER is used.
 173   ///
 174   UINT64                ExtendedSize;
 175 } EFI_FFS_FILE_HEADER2;
 176
 177 #define IS_FFS_FILE2(FfsFileHeaderPtr) \
 178     (((((EFI_FFS_FILE_HEADER *) (UINTN) FfsFileHeaderPtr)->Attributes) & FFS_ATTRIB_LARGE_FILE) == FFS_ATTRIB_LARGE_FILE)
 179
 180 ///
 181 /// The argument passed as the FfsFileHeaderPtr parameter to the
 182 /// FFS_FILE_SIZE() function-like macro below must not have side effects:
 183 /// FfsFileHeaderPtr is evaluated multiple times.
 184 ///
 185 #define FFS_FILE_SIZE(FfsFileHeaderPtr)  ((UINT32) (\
 186     (((EFI_FFS_FILE_HEADER *) (UINTN) (FfsFileHeaderPtr))->Size[0]      ) | \
 187     (((EFI_FFS_FILE_HEADER *) (UINTN) (FfsFileHeaderPtr))->Size[1] <<  8) | \
 188     (((EFI_FFS_FILE_HEADER *) (UINTN) (FfsFileHeaderPtr))->Size[2] << 16)))
 189
 190 #define FFS_FILE2_SIZE(FfsFileHeaderPtr) \
 191     ((UINT32) (((EFI_FFS_FILE_HEADER2 *) (UINTN) FfsFileHeaderPtr)->ExtendedSize))
 192
 193 typedef UINT8 EFI_SECTION_TYPE;
 194
 195 ///
 196 /// Pseudo type. It is used as a wild card when retrieving sections.
 197 ///  The section type EFI_SECTION_ALL matches all section types.
 198 ///
 199 #define EFI_SECTION_ALL  0x00
 200
 201 ///
 202 /// Encapsulation section Type values.
 203 ///
 204 #define EFI_SECTION_COMPRESSION  0x01
 205
 206 #define EFI_SECTION_GUID_DEFINED  0x02
 207
 208 #define EFI_SECTION_DISPOSABLE  0x03
 209
 210 ///
 211 /// Leaf section Type values.
 212 ///
 213 #define EFI_SECTION_PE32                   0x10
 214 #define EFI_SECTION_PIC                    0x11
 215 #define EFI_SECTION_TE                     0x12
 216 #define EFI_SECTION_DXE_DEPEX              0x13
 217 #define EFI_SECTION_VERSION                0x14
 218 #define EFI_SECTION_USER_INTERFACE         0x15
 219 #define EFI_SECTION_COMPATIBILITY16        0x16
 220 #define EFI_SECTION_FIRMWARE_VOLUME_IMAGE  0x17
 221 #define EFI_SECTION_FREEFORM_SUBTYPE_GUID  0x18
 222 #define EFI_SECTION_RAW                    0x19
 223 #define EFI_SECTION_PEI_DEPEX              0x1B
 224 #define EFI_SECTION_MM_DEPEX               0x1C
 225 #define EFI_SECTION_SMM_DEPEX              EFI_SECTION_MM_DEPEX
 226
 227 ///
 228 /// Common section header.
 229 ///
 230 typedef struct {
 231   ///
 232   /// A 24-bit unsigned integer that contains the total size of the section in bytes,
 233   /// including the EFI_COMMON_SECTION_HEADER.
 234   ///
 235   UINT8               Size[3];
 236   EFI_SECTION_TYPE    Type;
 237   ///
 238   /// Declares the section type.
 239   ///
 240 } EFI_COMMON_SECTION_HEADER;
 241
 242 typedef struct {
 243   ///
 244   /// A 24-bit unsigned integer that contains the total size of the section in bytes,
 245   /// including the EFI_COMMON_SECTION_HEADER.
 246   ///
 247   UINT8               Size[3];
 248
 249   EFI_SECTION_TYPE    Type;
 250
 251   ///
 252   /// If Size is 0xFFFFFF, then ExtendedSize contains the size of the section. If
 253   /// Size is not equal to 0xFFFFFF, then this field does not exist.
 254   ///
 255   UINT32              ExtendedSize;
 256 } EFI_COMMON_SECTION_HEADER2;
 257
 258 ///
 259 /// Leaf section type that contains an
 260 /// IA-32 16-bit executable image.
 261 ///
 262 typedef EFI_COMMON_SECTION_HEADER  EFI_COMPATIBILITY16_SECTION;
 263 typedef EFI_COMMON_SECTION_HEADER2 EFI_COMPATIBILITY16_SECTION2;
 264
 265 ///
 266 /// CompressionType of EFI_COMPRESSION_SECTION.
 267 ///
 268 #define EFI_NOT_COMPRESSED        0x00
 269 #define EFI_STANDARD_COMPRESSION  0x01
 270 ///
 271 /// An encapsulation section type in which the
 272 /// section data is compressed.
 273 ///
 274 typedef struct {
 275   ///
 276   /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.
 277   ///
 278   EFI_COMMON_SECTION_HEADER    CommonHeader;
 279   ///
 280   /// The UINT32 that indicates the size of the section data after decompression.
 281   ///
 282   UINT32                       UncompressedLength;
 283   ///
 284   /// Indicates which compression algorithm is used.
 285   ///
 286   UINT8                        CompressionType;
 287 } EFI_COMPRESSION_SECTION;
 288
 289 typedef struct {
 290   ///
 291   /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.
 292   ///
 293   EFI_COMMON_SECTION_HEADER2    CommonHeader;
 294   ///
 295   /// UINT32 that indicates the size of the section data after decompression.
 296   ///
 297   UINT32                        UncompressedLength;
 298   ///
 299   /// Indicates which compression algorithm is used.
 300   ///
 301   UINT8                         CompressionType;
 302 } EFI_COMPRESSION_SECTION2;
 303
 304 ///
 305 /// An encapsulation section type in which the section data is disposable.
 306 /// A disposable section is an encapsulation section in which the section data may be disposed of during
 307 /// the process of creating or updating a firmware image without significant impact on the usefulness of
 308 /// the file. The Type field in the section header is set to EFI_SECTION_DISPOSABLE. This
 309 /// allows optional or descriptive data to be included with the firmware file which can be removed in
 310 /// order to conserve space. The contents of this section are implementation specific, but might contain
 311 /// debug data or detailed integration instructions.
 312 ///
 313 typedef EFI_COMMON_SECTION_HEADER  EFI_DISPOSABLE_SECTION;
 314 typedef EFI_COMMON_SECTION_HEADER2 EFI_DISPOSABLE_SECTION2;
 315
 316 ///
 317 /// The leaf section which could be used to determine the dispatch order of DXEs.
 318 ///
 319 typedef EFI_COMMON_SECTION_HEADER  EFI_DXE_DEPEX_SECTION;
 320 typedef EFI_COMMON_SECTION_HEADER2 EFI_DXE_DEPEX_SECTION2;
 321
 322 ///
 323 /// The leaf section which contains a PI FV.
 324 ///
 325 typedef EFI_COMMON_SECTION_HEADER  EFI_FIRMWARE_VOLUME_IMAGE_SECTION;
 326 typedef EFI_COMMON_SECTION_HEADER2 EFI_FIRMWARE_VOLUME_IMAGE_SECTION2;
 327
 328 ///
 329 /// The leaf section which contains a single GUID.
 330 ///
 331 typedef struct {
 332   ///
 333   /// Common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.
 334   ///
 335   EFI_COMMON_SECTION_HEADER    CommonHeader;
 336   ///
 337   /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
 338   ///
 339   EFI_GUID                     SubTypeGuid;
 340 } EFI_FREEFORM_SUBTYPE_GUID_SECTION;
 341
 342 typedef struct {
 343   ///
 344   /// The common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.
 345   ///
 346   EFI_COMMON_SECTION_HEADER2    CommonHeader;
 347   ///
 348   /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
 349   ///
 350   EFI_GUID                      SubTypeGuid;
 351 } EFI_FREEFORM_SUBTYPE_GUID_SECTION2;
 352
 353 ///
 354 /// Attributes of EFI_GUID_DEFINED_SECTION.
 355 ///
 356 #define EFI_GUIDED_SECTION_PROCESSING_REQUIRED  0x01
 357 #define EFI_GUIDED_SECTION_AUTH_STATUS_VALID    0x02
 358 ///
 359 /// The leaf section which is encapsulation defined by specific GUID.
 360 ///
 361 typedef struct {
 362   ///
 363   /// The common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.
 364   ///
 365   EFI_COMMON_SECTION_HEADER    CommonHeader;
 366   ///
 367   /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
 368   ///
 369   EFI_GUID                     SectionDefinitionGuid;
 370   ///
 371   /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
 372   ///
 373   UINT16                       DataOffset;
 374   ///
 375   /// The bit field that declares some specific characteristics of the section contents.
 376   ///
 377   UINT16                       Attributes;
 378 } EFI_GUID_DEFINED_SECTION;
 379
 380 typedef struct {
 381   ///
 382   /// The common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.
 383   ///
 384   EFI_COMMON_SECTION_HEADER2    CommonHeader;
 385   ///
 386   /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
 387   ///
 388   EFI_GUID                      SectionDefinitionGuid;
 389   ///
 390   /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
 391   ///
 392   UINT16                        DataOffset;
 393   ///
 394   /// The bit field that declares some specific characteristics of the section contents.
 395   ///
 396   UINT16                        Attributes;
 397 } EFI_GUID_DEFINED_SECTION2;
 398
 399 ///
 400 /// The leaf section which contains PE32+ image.
 401 ///
 402 typedef EFI_COMMON_SECTION_HEADER  EFI_PE32_SECTION;
 403 typedef EFI_COMMON_SECTION_HEADER2 EFI_PE32_SECTION2;
 404
 405 ///
 406 /// The leaf section used to determine the dispatch order of PEIMs.
 407 ///
 408 typedef EFI_COMMON_SECTION_HEADER  EFI_PEI_DEPEX_SECTION;
 409 typedef EFI_COMMON_SECTION_HEADER2 EFI_PEI_DEPEX_SECTION2;
 410
 411 ///
 412 /// A leaf section type that contains a position-independent-code (PIC) image.
 413 /// A PIC image section is a leaf section that contains a position-independent-code (PIC) image.
 414 /// In addition to normal PE32+ images that contain relocation information, PEIM executables may be
 415 /// PIC and are referred to as PIC images. A PIC image is the same as a PE32+ image except that all
 416 /// relocation information has been stripped from the image and the image can be moved and will
 417 /// execute correctly without performing any relocation or other fix-ups. EFI_PIC_SECTION2 must
 418 /// be used if the section is 16MB or larger.
 419 ///
 420 typedef EFI_COMMON_SECTION_HEADER  EFI_PIC_SECTION;
 421 typedef EFI_COMMON_SECTION_HEADER2 EFI_PIC_SECTION2;
 422
 423 ///
 424 /// The leaf section which constains the position-independent-code image.
 425 ///
 426 typedef EFI_COMMON_SECTION_HEADER  EFI_TE_SECTION;
 427 typedef EFI_COMMON_SECTION_HEADER2 EFI_TE_SECTION2;
 428
 429 ///
 430 /// The leaf section which contains an array of zero or more bytes.
 431 ///
 432 typedef EFI_COMMON_SECTION_HEADER  EFI_RAW_SECTION;
 433 typedef EFI_COMMON_SECTION_HEADER2 EFI_RAW_SECTION2;
 434
 435 ///
 436 /// The SMM dependency expression section is a leaf section that contains a dependency expression that
 437 /// is used to determine the dispatch order for SMM drivers. Before the SMRAM invocation of the
 438 /// SMM driver's entry point, this dependency expression must evaluate to TRUE. See the Platform
 439 /// Initialization Specification, Volume 2, for details regarding the format of the dependency expression.
 440 /// The dependency expression may refer to protocols installed in either the UEFI or the SMM protocol
 441 /// database. EFI_SMM_DEPEX_SECTION2 must be used if the section is 16MB or larger.
 442 ///
 443 typedef EFI_COMMON_SECTION_HEADER  EFI_SMM_DEPEX_SECTION;
 444 typedef EFI_COMMON_SECTION_HEADER2 EFI_SMM_DEPEX_SECTION2;
 445
 446 ///
 447 /// The leaf section which contains a unicode string that
 448 /// is human readable file name.
 449 ///
 450 typedef struct {
 451   EFI_COMMON_SECTION_HEADER    CommonHeader;
 452
 453   ///
 454   /// Array of unicode string.
 455   ///
 456   CHAR16                       FileNameString[1];
 457 } EFI_USER_INTERFACE_SECTION;
 458
 459 typedef struct {
 460   EFI_COMMON_SECTION_HEADER2    CommonHeader;
 461   CHAR16                        FileNameString[1];
 462 } EFI_USER_INTERFACE_SECTION2;
 463
 464 ///
 465 /// The leaf section which contains a numeric build number and
 466 /// an optional unicode string that represents the file revision.
 467 ///
 468 typedef struct {
 469   EFI_COMMON_SECTION_HEADER    CommonHeader;
 470   UINT16                       BuildNumber;
 471
 472   ///
 473   /// Array of unicode string.
 474   ///
 475   CHAR16                       VersionString[1];
 476 } EFI_VERSION_SECTION;
 477
 478 typedef struct {
 479   EFI_COMMON_SECTION_HEADER2    CommonHeader;
 480   ///
 481   /// A UINT16 that represents a particular build. Subsequent builds have monotonically
 482   /// increasing build numbers relative to earlier builds.
 483   ///
 484   UINT16                        BuildNumber;
 485   CHAR16                        VersionString[1];
 486 } EFI_VERSION_SECTION2;
 487
 488 ///
 489 /// The argument passed as the SectionHeaderPtr parameter to the SECTION_SIZE()
 490 /// and IS_SECTION2() function-like macros below must not have side effects:
 491 /// SectionHeaderPtr is evaluated multiple times.
 492 ///
 493 #define SECTION_SIZE(SectionHeaderPtr)  ((UINT32) (\
 494     (((EFI_COMMON_SECTION_HEADER *) (UINTN) (SectionHeaderPtr))->Size[0]      ) | \
 495     (((EFI_COMMON_SECTION_HEADER *) (UINTN) (SectionHeaderPtr))->Size[1] <<  8) | \
 496     (((EFI_COMMON_SECTION_HEADER *) (UINTN) (SectionHeaderPtr))->Size[2] << 16)))
 497
 498 #define IS_SECTION2(SectionHeaderPtr) \
 499     (SECTION_SIZE (SectionHeaderPtr) == 0x00ffffff)
 500
 501 #define SECTION2_SIZE(SectionHeaderPtr) \
 502     (((EFI_COMMON_SECTION_HEADER2 *) (UINTN) SectionHeaderPtr)->ExtendedSize)
 503
 504 #pragma pack()
 505
 506 #endif