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