iPXE
PiFirmwareFile.h
Go to the documentation of this file.
1 /** @file
2  The firmware file related definitions in PI.
3 
4 Copyright (c) 2006 - 2015, 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.4.
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  ///
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  ///
46  } Checksum;
47  ///
48  /// This is the full 16 bits of the IntegrityCheck field.
49  ///
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 
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  ///
115  ///
116  /// Used to verify the integrity of the file.
117  ///
119  ///
120  /// Identifies the type of file.
121  ///
123  ///
124  /// Declares various file attribute bits.
125  ///
127  ///
128  /// The length of the file in bytes, including the FFS header.
129  ///
131  ///
132  /// Used to track the state of the file throughout the life of the file from creation to deletion.
133  ///
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  ///
144 
145  ///
146  /// Used to verify the integrity of the file.
147  ///
149 
150  ///
151  /// Identifies the type of file.
152  ///
154 
155  ///
156  /// Declares various file attribute bits.
157  ///
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  ///
168 
169  ///
170  /// Used to track the state of the file throughout the life of the file from creation to deletion.
171  ///
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  ///
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  ((UINT32) (((EFI_FFS_FILE_HEADER2 *) (UINTN) FfsFileHeaderPtr)->ExtendedSize))
189 
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  ///
233  ///
234  /// Declares the section type.
235  ///
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  ///
244 
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  ///
253 
254 ///
255 /// Leaf section type that contains an
256 /// IA-32 16-bit executable image.
257 ///
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  ///
275  ///
276  /// The UINT32 that indicates the size of the section data after decompression.
277  ///
279  ///
280  /// Indicates which compression algorithm is used.
281  ///
284 
285 typedef struct {
286  ///
287  /// Usual common section header. CommonHeader.Type = EFI_SECTION_COMPRESSION.
288  ///
290  ///
291  /// UINT32 that indicates the size of the section data after decompression.
292  ///
294  ///
295  /// Indicates which compression algorithm is used.
296  ///
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 ///
311 
312 ///
313 /// The leaf section which could be used to determine the dispatch order of DXEs.
314 ///
317 
318 ///
319 /// The leaf section which contains a PI FV.
320 ///
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  ///
332  ///
333  /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
334  ///
337 
338 typedef struct {
339  ///
340  /// The common section header. CommonHeader.Type = EFI_SECTION_FREEFORM_SUBTYPE_GUID.
341  ///
343  ///
344  /// This GUID is defined by the creator of the file. It is a vendor-defined file type.
345  ///
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  ///
362  ///
363  /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
364  ///
366  ///
367  /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
368  ///
370  ///
371  /// The bit field that declares some specific characteristics of the section contents.
372  ///
375 
376 typedef struct {
377  ///
378  /// The common section header. CommonHeader.Type = EFI_SECTION_GUID_DEFINED.
379  ///
381  ///
382  /// The GUID that defines the format of the data that follows. It is a vendor-defined section type.
383  ///
385  ///
386  /// Contains the offset in bytes from the beginning of the common header to the first byte of the data.
387  ///
389  ///
390  /// The bit field that declares some specific characteristics of the section contents.
391  ///
394 
395 ///
396 /// The leaf section which contains PE32+ image.
397 ///
400 
401 ///
402 /// The leaf section used to determine the dispatch order of PEIMs.
403 ///
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 ///
418 
419 ///
420 /// The leaf section which constains the position-independent-code image.
421 ///
424 
425 ///
426 /// The leaf section which contains an array of zero or more bytes.
427 ///
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 ///
441 
442 ///
443 /// The leaf section which contains a unicode string that
444 /// is human readable file name.
445 ///
446 typedef struct {
448 
449  ///
450  /// Array of unicode string.
451  ///
452  CHAR16 FileNameString[1];
454 
455 typedef struct {
457  CHAR16 FileNameString[1];
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 {
467 
468  ///
469  /// Array of unicode string.
470  ///
471  CHAR16 VersionString[1];
473 
474 typedef struct {
476  ///
477  /// A UINT16 that represents a particular build. Subsequent builds have monotonically
478  /// increasing build numbers relative to earlier builds.
479  ///
481  CHAR16 VersionString[1];
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 
The leaf section which contains a unicode string that is human readable file name.
EFI_FV_FILETYPE Type
Identifies the type of file.
UINT32 ExtendedSize
If Size is 0xFFFFFF, then ExtendedSize contains the size of the section.
UINT32 UncompressedLength
UINT32 that indicates the size of the section data after decompression.
EFI_GUID SectionDefinitionGuid
The GUID that defines the format of the data that follows.
EFI_COMMON_SECTION_HEADER2 CommonHeader
The common section header.
EFI_FFS_FILE_STATE State
Used to track the state of the file throughout the life of the file from creation to deletion.
128 bit buffer containing a unique identifier value.
Definition: Base.h:263
UINT16 DataOffset
Contains the offset in bytes from the beginning of the common header to the first byte of the data.
EFI_COMMON_SECTION_HEADER2 EFI_TE_SECTION2
EFI_FFS_FILE_STATE State
Used to track the state of the file throughout the life of the file from creation to deletion.
UINT16 Checksum16
This is the full 16 bits of the IntegrityCheck field.
unsigned int UINT32
Definition: ProcessorBind.h:56
EFI_FFS_INTEGRITY_CHECK IntegrityCheck
Used to verify the integrity of the file.
EFI_COMMON_SECTION_HEADER EFI_DXE_DEPEX_SECTION
The leaf section which could be used to determine the dispatch order of DXEs.
unsigned short CHAR16
Definition: ProcessorBind.h:59
UINT32 UncompressedLength
The UINT32 that indicates the size of the section data after decompression.
EFI_COMMON_SECTION_HEADER CommonHeader
Common section header.
UINT8_t Checksum
Checksum.
Definition: pxe_api.h:76
EFI_GUID SubTypeGuid
This GUID is defined by the creator of the file.
unsigned char UINT8
Definition: ProcessorBind.h:62
UINT8 EFI_FFS_FILE_STATE
EFI_COMMON_SECTION_HEADER2 CommonHeader
FILE_LICENCE(BSD3)
Used to verify the integrity of the file.
EFI_GUID Name
This GUID is the file name.
UINT16_t Size
Size of structure.
Definition: pxe_api.h:58
UINT8 CompressionType
Indicates which compression algorithm is used.
UINT8 Header
The IntegrityCheck.Checksum.Header field is an 8-bit checksum of the file header.
EFI_GUID SectionDefinitionGuid
The GUID that defines the format of the data that follows.
EFI_COMMON_SECTION_HEADER EFI_FIRMWARE_VOLUME_IMAGE_SECTION
The leaf section which contains a PI FV.
EFI_COMMON_SECTION_HEADER EFI_RAW_SECTION
The leaf section which contains an array of zero or more bytes.
EFI_FFS_FILE_ATTRIBUTES Attributes
Declares various file attribute bits.
EFI_COMMON_SECTION_HEADER2 CommonHeader
Usual common section header.
UINT64 ExtendedSize
If FFS_ATTRIB_LARGE_FILE is set in Attributes, then ExtendedSize exists and Size must be set to zero.
UINT8 EFI_FFS_FILE_ATTRIBUTES
EFI_COMMON_SECTION_HEADER CommonHeader
EFI_COMMON_SECTION_HEADER2 EFI_PIC_SECTION2
EFI_COMMON_SECTION_HEADER CommonHeader
EFI_COMMON_SECTION_HEADER EFI_PE32_SECTION
The leaf section which contains PE32+ image.
UINT16 Attributes
The bit field that declares some specific characteristics of the section contents.
UINT16 DataOffset
Contains the offset in bytes from the beginning of the common header to the first byte of the data.
unsigned short UINT16
Definition: ProcessorBind.h:58
EFI_FFS_INTEGRITY_CHECK IntegrityCheck
Used to verify the integrity of the file.
EFI_FFS_FILE_ATTRIBUTES Attributes
Declares various file attribute bits.
An encapsulation section type in which the section data is compressed.
EFI_COMMON_SECTION_HEADER2 CommonHeader
UINT16 BuildNumber
A UINT16 that represents a particular build.
EFI_COMMON_SECTION_HEADER2 EFI_FIRMWARE_VOLUME_IMAGE_SECTION2
EFI_COMMON_SECTION_HEADER EFI_COMPATIBILITY16_SECTION
Leaf section type that contains an IA-32 16-bit executable image.
unsigned long long UINT64
Definition: ProcessorBind.h:54
EFI_COMMON_SECTION_HEADER2 EFI_COMPATIBILITY16_SECTION2
EFI_COMMON_SECTION_HEADER2 EFI_DXE_DEPEX_SECTION2
The leaf section which contains a numeric build number and an optional unicode string that represents...
Each file begins with the header that describe the contents and state of the files.
The leaf section which is encapsulation defined by specific GUID.
UINT16 Attributes
The bit field that declares some specific characteristics of the section contents.
UINT8 EFI_SECTION_TYPE
EFI_COMMON_SECTION_HEADER EFI_DISPOSABLE_SECTION
An encapsulation section type in which the section data is disposable.
EFI_FV_FILETYPE Type
Identifies the type of file.
EFI_COMMON_SECTION_HEADER CommonHeader
Usual common section header.
EFI_COMMON_SECTION_HEADER2 EFI_PEI_DEPEX_SECTION2
UINT8 File
If the FFS_ATTRIB_CHECKSUM (see definition below) bit of the Attributes field is set to one,...
EFI_COMMON_SECTION_HEADER2 CommonHeader
The common section header.
EFI_GUID SubTypeGuid
This GUID is defined by the creator of the file.
UINT8 EFI_FV_FILETYPE
EFI_COMMON_SECTION_HEADER EFI_SMM_DEPEX_SECTION
The SMM dependency expression section is a leaf section that contains a dependency expression that is...
EFI_COMMON_SECTION_HEADER EFI_PEI_DEPEX_SECTION
The leaf section used to determine the dispatch order of PEIMs.
EFI_GUID Name
This GUID is the file name.
Common section header.
EFI_COMMON_SECTION_HEADER EFI_PIC_SECTION
A leaf section type that contains a position-independent-code (PIC) image.
EFI_COMMON_SECTION_HEADER2 EFI_PE32_SECTION2
EFI_COMMON_SECTION_HEADER2 EFI_DISPOSABLE_SECTION2
UINT8 CompressionType
Indicates which compression algorithm is used.
EFI_COMMON_SECTION_HEADER CommonHeader
The common section header.
The leaf section which contains a single GUID.
EFI_COMMON_SECTION_HEADER2 EFI_SMM_DEPEX_SECTION2
EFI_COMMON_SECTION_HEADER EFI_TE_SECTION
The leaf section which constains the position-independent-code image.
EFI_COMMON_SECTION_HEADER2 EFI_RAW_SECTION2