MdePkg/Include/Pi/PiFirmwareFile.h

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