iPXE
PiFirmwareFile.h
Go to the documentation of this file.
00001 /** @file
00002   The firmware file related definitions in PI.
00003 
00004 Copyright (c) 2006 - 2015, Intel Corporation. All rights reserved.<BR>
00005 This program and the accompanying materials are licensed and made available under
00006 the terms and conditions of the BSD License that accompanies this distribution.
00007 The full text of the license may be found at
00008 http://opensource.org/licenses/bsd-license.php.
00009 
00010 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
00011 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
00012 
00013   @par Revision Reference:
00014   PI Version 1.4.
00015 
00016 **/
00017 
00018 
00019 #ifndef __PI_FIRMWARE_FILE_H__
00020 #define __PI_FIRMWARE_FILE_H__
00021 
00022 FILE_LICENCE ( BSD3 );
00023 
00024 #pragma pack(1)
00025 ///
00026 /// Used to verify the integrity of the file.
00027 ///
00028 typedef union {
00029   struct {
00030     ///
00031     /// The IntegrityCheck.Checksum.Header field is an 8-bit checksum of the file
00032     /// header. The State and IntegrityCheck.Checksum.File fields are assumed
00033     /// to be zero and the checksum is calculated such that the entire header sums to zero.
00034     ///
00035     UINT8   Header;
00036     ///
00037     /// If the FFS_ATTRIB_CHECKSUM (see definition below) bit of the Attributes
00038     /// field is set to one, the IntegrityCheck.Checksum.File field is an 8-bit
00039     /// checksum of the file data.
00040     /// If the FFS_ATTRIB_CHECKSUM bit of the Attributes field is cleared to zero,
00041     /// the IntegrityCheck.Checksum.File field must be initialized with a value of
00042     /// 0xAA. The IntegrityCheck.Checksum.File field is valid any time the
00043     /// EFI_FILE_DATA_VALID bit is set in the State field.
00044     ///
00045     UINT8   File;
00046   } Checksum;
00047   ///
00048   /// This is the full 16 bits of the IntegrityCheck field.
00049   ///
00050   UINT16    Checksum16;
00051 } EFI_FFS_INTEGRITY_CHECK;
00052 
00053 ///
00054 /// FFS_FIXED_CHECKSUM is the checksum value used when the
00055 /// FFS_ATTRIB_CHECKSUM attribute bit is clear.
00056 ///
00057 #define FFS_FIXED_CHECKSUM  0xAA
00058 
00059 typedef UINT8 EFI_FV_FILETYPE;
00060 typedef UINT8 EFI_FFS_FILE_ATTRIBUTES;
00061 typedef UINT8 EFI_FFS_FILE_STATE;
00062 
00063 ///
00064 /// File Types Definitions
00065 ///
00066 #define EFI_FV_FILETYPE_ALL                   0x00
00067 #define EFI_FV_FILETYPE_RAW                   0x01
00068 #define EFI_FV_FILETYPE_FREEFORM              0x02
00069 #define EFI_FV_FILETYPE_SECURITY_CORE         0x03
00070 #define EFI_FV_FILETYPE_PEI_CORE              0x04
00071 #define EFI_FV_FILETYPE_DXE_CORE              0x05
00072 #define EFI_FV_FILETYPE_PEIM                  0x06
00073 #define EFI_FV_FILETYPE_DRIVER                0x07
00074 #define EFI_FV_FILETYPE_COMBINED_PEIM_DRIVER  0x08
00075 #define EFI_FV_FILETYPE_APPLICATION           0x09
00076 #define EFI_FV_FILETYPE_SMM                   0x0A
00077 #define EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE 0x0B
00078 #define EFI_FV_FILETYPE_COMBINED_SMM_DXE      0x0C
00079 #define EFI_FV_FILETYPE_SMM_CORE              0x0D
00080 #define EFI_FV_FILETYPE_OEM_MIN               0xc0
00081 #define EFI_FV_FILETYPE_OEM_MAX               0xdf
00082 #define EFI_FV_FILETYPE_DEBUG_MIN             0xe0
00083 #define EFI_FV_FILETYPE_DEBUG_MAX             0xef
00084 #define EFI_FV_FILETYPE_FFS_MIN               0xf0
00085 #define EFI_FV_FILETYPE_FFS_MAX               0xff
00086 #define EFI_FV_FILETYPE_FFS_PAD               0xf0
00087 ///
00088 /// FFS File Attributes.
00089 ///
00090 #define FFS_ATTRIB_LARGE_FILE         0x01
00091 #define FFS_ATTRIB_FIXED              0x04
00092 #define FFS_ATTRIB_DATA_ALIGNMENT     0x38
00093 #define FFS_ATTRIB_CHECKSUM           0x40
00094 
00095 ///
00096 /// FFS File State Bits.
00097 ///
00098 #define EFI_FILE_HEADER_CONSTRUCTION  0x01
00099 #define EFI_FILE_HEADER_VALID         0x02
00100 #define EFI_FILE_DATA_VALID           0x04
00101 #define EFI_FILE_MARKED_FOR_UPDATE    0x08
00102 #define EFI_FILE_DELETED              0x10
00103 #define EFI_FILE_HEADER_INVALID       0x20
00104 
00105 
00106 ///
00107 /// Each file begins with the header that describe the
00108 /// contents and state of the files.
00109 ///
00110 typedef struct {
00111   ///
00112   /// This GUID is the file name. It is used to uniquely identify the file.
00113   ///
00114   EFI_GUID                Name;
00115   ///
00116   /// Used to verify the integrity of the file.
00117   ///
00118   EFI_FFS_INTEGRITY_CHECK IntegrityCheck;
00119   ///
00120   /// Identifies the type of file.
00121   ///
00122   EFI_FV_FILETYPE         Type;
00123   ///
00124   /// Declares various file attribute bits.
00125   ///
00126   EFI_FFS_FILE_ATTRIBUTES Attributes;
00127   ///
00128   /// The length of the file in bytes, including the FFS header.
00129   ///
00130   UINT8                   Size[3];
00131   ///
00132   /// Used to track the state of the file throughout the life of the file from creation to deletion.
00133   ///
00134   EFI_FFS_FILE_STATE      State;
00135 } EFI_FFS_FILE_HEADER;
00136 
00137 typedef struct {
00138   ///
00139   /// This GUID is the file name. It is used to uniquely identify the file. There may be only
00140   /// one instance of a file with the file name GUID of Name in any given firmware
00141   /// volume, except if the file type is EFI_FV_FILETYPE_FFS_PAD.
00142   ///
00143   EFI_GUID                  Name;
00144 
00145   ///
00146   /// Used to verify the integrity of the file.
00147   ///
00148   EFI_FFS_INTEGRITY_CHECK   IntegrityCheck;
00149 
00150   ///
00151   /// Identifies the type of file.
00152   ///
00153   EFI_FV_FILETYPE           Type;
00154 
00155   ///
00156   /// Declares various file attribute bits.
00157   ///
00158   EFI_FFS_FILE_ATTRIBUTES   Attributes;
00159 
00160   ///
00161   /// The length of the file in bytes, including the FFS header.
00162   /// The length of the file data is either (Size - sizeof(EFI_FFS_FILE_HEADER)). This calculation means a
00163   /// zero-length file has a Size of 24 bytes, which is sizeof(EFI_FFS_FILE_HEADER).
00164   /// Size is not required to be a multiple of 8 bytes. Given a file F, the next file header is
00165   /// located at the next 8-byte aligned firmware volume offset following the last byte of the file F.
00166   ///
00167   UINT8                     Size[3];
00168 
00169   ///
00170   /// Used to track the state of the file throughout the life of the file from creation to deletion.
00171   ///
00172   EFI_FFS_FILE_STATE        State;
00173 
00174   ///
00175   /// If FFS_ATTRIB_LARGE_FILE is set in Attributes, then ExtendedSize exists and Size must be set to zero.
00176   /// If FFS_ATTRIB_LARGE_FILE is not set then EFI_FFS_FILE_HEADER is used.
00177   ///
00178   UINT64                    ExtendedSize;
00179 } EFI_FFS_FILE_HEADER2;
00180 
00181 #define IS_FFS_FILE2(FfsFileHeaderPtr) \
00182     (((((EFI_FFS_FILE_HEADER *) (UINTN) FfsFileHeaderPtr)->Attributes) & FFS_ATTRIB_LARGE_FILE) == FFS_ATTRIB_LARGE_FILE)
00183 
00184 #define FFS_FILE_SIZE(FfsFileHeaderPtr) \
00185     ((UINT32) (*((UINT32 *) ((EFI_FFS_FILE_HEADER *) (UINTN) FfsFileHeaderPtr)->Size) & 0x00ffffff))
00186 
00187 #define FFS_FILE2_SIZE(FfsFileHeaderPtr) \
00188     ((UINT32) (((EFI_FFS_FILE_HEADER2 *) (UINTN) FfsFileHeaderPtr)->ExtendedSize))
00189 
00190 typedef UINT8 EFI_SECTION_TYPE;
00191 
00192 ///
00193 /// Pseudo type. It is used as a wild card when retrieving sections.
00194 ///  The section type EFI_SECTION_ALL matches all section types.
00195 ///
00196 #define EFI_SECTION_ALL                   0x00
00197 
00198 ///
00199 /// Encapsulation section Type values.
00200 ///
00201 #define EFI_SECTION_COMPRESSION           0x01
00202 
00203 #define EFI_SECTION_GUID_DEFINED          0x02
00204 
00205 #define EFI_SECTION_DISPOSABLE            0x03
00206 
00207 ///
00208 /// Leaf section Type values.
00209 ///
00210 #define EFI_SECTION_PE32                  0x10
00211 #define EFI_SECTION_PIC                   0x11
00212 #define EFI_SECTION_TE                    0x12
00213 #define EFI_SECTION_DXE_DEPEX             0x13
00214 #define EFI_SECTION_VERSION               0x14
00215 #define EFI_SECTION_USER_INTERFACE        0x15
00216 #define EFI_SECTION_COMPATIBILITY16       0x16
00217 #define EFI_SECTION_FIRMWARE_VOLUME_IMAGE 0x17
00218 #define EFI_SECTION_FREEFORM_SUBTYPE_GUID 0x18
00219 #define EFI_SECTION_RAW                   0x19
00220 #define EFI_SECTION_PEI_DEPEX             0x1B
00221 #define EFI_SECTION_SMM_DEPEX             0x1C
00222 
00223 ///
00224 /// Common section header.
00225 ///
00226 typedef struct {
00227   ///
00228   /// A 24-bit unsigned integer that contains the total size of the section in bytes,
00229   /// including the EFI_COMMON_SECTION_HEADER.
00230   ///
00231   UINT8             Size[3];
00232   EFI_SECTION_TYPE  Type;
00233   ///
00234   /// Declares the section type.
00235   ///
00236 } EFI_COMMON_SECTION_HEADER;
00237 
00238 typedef struct {
00239   ///
00240   /// A 24-bit unsigned integer that contains the total size of the section in bytes,
00241   /// including the EFI_COMMON_SECTION_HEADER.
00242   ///
00243   UINT8             Size[3];
00244 
00245   EFI_SECTION_TYPE  Type;
00246 
00247   ///
00248   /// If Size is 0xFFFFFF, then ExtendedSize contains the size of the section. If
00249   /// Size is not equal to 0xFFFFFF, then this field does not exist.
00250   ///
00251   UINT32            ExtendedSize;
00252 } EFI_COMMON_SECTION_HEADER2;
00253 
00254 ///
00255 /// Leaf section type that contains an
00256 /// IA-32 16-bit executable image.
00257 ///
00258 typedef EFI_COMMON_SECTION_HEADER  EFI_COMPATIBILITY16_SECTION;
00259 typedef EFI_COMMON_SECTION_HEADER2 EFI_COMPATIBILITY16_SECTION2;
00260 
00261 ///
00262 /// CompressionType of EFI_COMPRESSION_SECTION.
00263 ///
00264 #define EFI_NOT_COMPRESSED        0x00
00265 #define EFI_STANDARD_COMPRESSION  0x01
00266 ///
00267 /// An encapsulation section type in which the
00268 /// section data is compressed.
00269 ///
00270 typedef struct {
00271   ///
00272   /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.
00273   ///
00274   EFI_COMMON_SECTION_HEADER   CommonHeader;
00275   ///
00276   /// The UINT32 that indicates the size of the section data after decompression.
00277   ///
00278   UINT32                      UncompressedLength;
00279   ///
00280   /// Indicates which compression algorithm is used.
00281   ///
00282   UINT8                       CompressionType;
00283 } EFI_COMPRESSION_SECTION;
00284 
00285 typedef struct {
00286   ///
00287   /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.
00288   ///
00289   EFI_COMMON_SECTION_HEADER2    CommonHeader;
00290   ///
00291   /// UINT32 that indicates the size of the section data after decompression.
00292   ///
00293   UINT32                        UncompressedLength;
00294   ///
00295   /// Indicates which compression algorithm is used.
00296   ///
00297   UINT8                         CompressionType;
00298 } EFI_COMPRESSION_SECTION2;
00299 
00300 ///
00301 /// An encapsulation section type in which the section data is disposable.
00302 /// A disposable section is an encapsulation section in which the section data may be disposed of during
00303 /// the process of creating or updating a firmware image without significant impact on the usefulness of
00304 /// the file. The Type field in the section header is set to EFI_SECTION_DISPOSABLE. This
00305 /// allows optional or descriptive data to be included with the firmware file which can be removed in
00306 /// order to conserve space. The contents of this section are implementation specific, but might contain
00307 /// debug data or detailed integration instructions.
00308 ///
00309 typedef EFI_COMMON_SECTION_HEADER   EFI_DISPOSABLE_SECTION;
00310 typedef EFI_COMMON_SECTION_HEADER2  EFI_DISPOSABLE_SECTION2;
00311 
00312 ///
00313 /// The leaf section which could be used to determine the dispatch order of DXEs.
00314 ///
00315 typedef EFI_COMMON_SECTION_HEADER   EFI_DXE_DEPEX_SECTION;
00316 typedef EFI_COMMON_SECTION_HEADER2  EFI_DXE_DEPEX_SECTION2;
00317 
00318 ///
00319 /// The leaf section which contains a PI FV.
00320 ///
00321 typedef EFI_COMMON_SECTION_HEADER   EFI_FIRMWARE_VOLUME_IMAGE_SECTION;
00322 typedef EFI_COMMON_SECTION_HEADER2  EFI_FIRMWARE_VOLUME_IMAGE_SECTION2;
00323 
00324 ///
00325 /// The leaf section which contains a single GUID.
00326 ///
00327 typedef struct {
00328   ///
00329   /// Common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.
00330   ///
00331   EFI_COMMON_SECTION_HEADER   CommonHeader;
00332   ///
00333   /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
00334   ///
00335   EFI_GUID                    SubTypeGuid;
00336 } EFI_FREEFORM_SUBTYPE_GUID_SECTION;
00337 
00338 typedef struct {
00339   ///
00340   /// The common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.
00341   ///
00342   EFI_COMMON_SECTION_HEADER2    CommonHeader;
00343   ///
00344   /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
00345   ///
00346   EFI_GUID                      SubTypeGuid;
00347 } EFI_FREEFORM_SUBTYPE_GUID_SECTION2;
00348 
00349 ///
00350 /// Attributes of EFI_GUID_DEFINED_SECTION.
00351 ///
00352 #define EFI_GUIDED_SECTION_PROCESSING_REQUIRED  0x01
00353 #define EFI_GUIDED_SECTION_AUTH_STATUS_VALID    0x02
00354 ///
00355 /// The leaf section which is encapsulation defined by specific GUID.
00356 ///
00357 typedef struct {
00358   ///
00359   /// The common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.
00360   ///
00361   EFI_COMMON_SECTION_HEADER   CommonHeader;
00362   ///
00363   /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
00364   ///
00365   EFI_GUID                    SectionDefinitionGuid;
00366   ///
00367   /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
00368   ///
00369   UINT16                      DataOffset;
00370   ///
00371   /// The bit field that declares some specific characteristics of the section contents.
00372   ///
00373   UINT16                      Attributes;
00374 } EFI_GUID_DEFINED_SECTION;
00375 
00376 typedef struct {
00377   ///
00378   /// The common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.
00379   ///
00380   EFI_COMMON_SECTION_HEADER2    CommonHeader;
00381   ///
00382   /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
00383   ///
00384   EFI_GUID                      SectionDefinitionGuid;
00385   ///
00386   /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
00387   ///
00388   UINT16                        DataOffset;
00389   ///
00390   /// The bit field that declares some specific characteristics of the section contents.
00391   ///
00392   UINT16                        Attributes;
00393 } EFI_GUID_DEFINED_SECTION2;
00394 
00395 ///
00396 /// The leaf section which contains PE32+ image.
00397 ///
00398 typedef EFI_COMMON_SECTION_HEADER   EFI_PE32_SECTION;
00399 typedef EFI_COMMON_SECTION_HEADER2  EFI_PE32_SECTION2;
00400 
00401 ///
00402 /// The leaf section used to determine the dispatch order of PEIMs.
00403 ///
00404 typedef EFI_COMMON_SECTION_HEADER   EFI_PEI_DEPEX_SECTION;
00405 typedef EFI_COMMON_SECTION_HEADER2  EFI_PEI_DEPEX_SECTION2;
00406 
00407 ///
00408 /// A leaf section type that contains a position-independent-code (PIC) image.
00409 /// A PIC image section is a leaf section that contains a position-independent-code (PIC) image.
00410 /// In addition to normal PE32+ images that contain relocation information, PEIM executables may be
00411 /// PIC and are referred to as PIC images. A PIC image is the same as a PE32+ image except that all
00412 /// relocation information has been stripped from the image and the image can be moved and will
00413 /// execute correctly without performing any relocation or other fix-ups. EFI_PIC_SECTION2 must
00414 /// be used if the section is 16MB or larger.
00415 ///
00416 typedef EFI_COMMON_SECTION_HEADER   EFI_PIC_SECTION;
00417 typedef EFI_COMMON_SECTION_HEADER2  EFI_PIC_SECTION2;
00418 
00419 ///
00420 /// The leaf section which constains the position-independent-code image.
00421 ///
00422 typedef EFI_COMMON_SECTION_HEADER   EFI_TE_SECTION;
00423 typedef EFI_COMMON_SECTION_HEADER2  EFI_TE_SECTION2;
00424 
00425 ///
00426 /// The leaf section which contains an array of zero or more bytes.
00427 ///
00428 typedef EFI_COMMON_SECTION_HEADER   EFI_RAW_SECTION;
00429 typedef EFI_COMMON_SECTION_HEADER2  EFI_RAW_SECTION2;
00430 
00431 ///
00432 /// The SMM dependency expression section is a leaf section that contains a dependency expression that
00433 /// is used to determine the dispatch order for SMM drivers. Before the SMRAM invocation of the
00434 /// SMM driver's entry point, this dependency expression must evaluate to TRUE. See the Platform
00435 /// Initialization Specification, Volume 2, for details regarding the format of the dependency expression.
00436 /// The dependency expression may refer to protocols installed in either the UEFI or the SMM protocol
00437 /// database. EFI_SMM_DEPEX_SECTION2 must be used if the section is 16MB or larger.
00438 ///
00439 typedef EFI_COMMON_SECTION_HEADER EFI_SMM_DEPEX_SECTION;
00440 typedef EFI_COMMON_SECTION_HEADER2 EFI_SMM_DEPEX_SECTION2;
00441 
00442 ///
00443 /// The leaf section which contains a unicode string that
00444 /// is human readable file name.
00445 ///
00446 typedef struct {
00447   EFI_COMMON_SECTION_HEADER   CommonHeader;
00448 
00449   ///
00450   /// Array of unicode string.
00451   ///
00452   CHAR16                      FileNameString[1];
00453 } EFI_USER_INTERFACE_SECTION;
00454 
00455 typedef struct {
00456   EFI_COMMON_SECTION_HEADER2    CommonHeader;
00457   CHAR16                        FileNameString[1];
00458 } EFI_USER_INTERFACE_SECTION2;
00459 
00460 ///
00461 /// The leaf section which contains a numeric build number and
00462 /// an optional unicode string that represents the file revision.
00463 ///
00464 typedef struct {
00465   EFI_COMMON_SECTION_HEADER   CommonHeader;
00466   UINT16                      BuildNumber;
00467 
00468   ///
00469   /// Array of unicode string.
00470   ///
00471   CHAR16                      VersionString[1];
00472 } EFI_VERSION_SECTION;
00473 
00474 typedef struct {
00475   EFI_COMMON_SECTION_HEADER2    CommonHeader;
00476   ///
00477   /// A UINT16 that represents a particular build. Subsequent builds have monotonically
00478   /// increasing build numbers relative to earlier builds.
00479   ///
00480   UINT16                        BuildNumber;
00481   CHAR16                        VersionString[1];
00482 } EFI_VERSION_SECTION2;
00483 
00484 #define IS_SECTION2(SectionHeaderPtr) \
00485     ((UINT32) (*((UINT32 *) ((EFI_COMMON_SECTION_HEADER *) (UINTN) SectionHeaderPtr)->Size) & 0x00ffffff) == 0x00ffffff)
00486 
00487 #define SECTION_SIZE(SectionHeaderPtr) \
00488     ((UINT32) (*((UINT32 *) ((EFI_COMMON_SECTION_HEADER *) (UINTN) SectionHeaderPtr)->Size) & 0x00ffffff))
00489 
00490 #define SECTION2_SIZE(SectionHeaderPtr) \
00491     (((EFI_COMMON_SECTION_HEADER2 *) (UINTN) SectionHeaderPtr)->ExtendedSize)
00492 
00493 #pragma pack()
00494 
00495 #endif
00496