qemu/roms/ipxe/src/include/ipxe/efi/Pi/PiFirmwareFile.h

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