]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Protocol/FirmwareVolume2.h
projects / mirror_edk2.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
MdePkg: Apply uncrustify changes
[mirror_edk2.git] / MdePkg / Include / Protocol / FirmwareVolume2.h
CommitLineData
d1f95000 1/** @file\r
9095d37b
LG		 2 The Firmware Volume Protocol provides file-level access to the firmware volume.\r
3 Each firmware volume driver must produce an instance of the\r
d1f95000 4 Firmware Volume Protocol if the firmware volume is to be visible to\r
5 the system during the DXE phase. The Firmware Volume Protocol also provides\r
6 mechanisms for determining and modifying some attributes of the firmware volume.\r
7\r
9095d37b 8 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
9344f092 9 SPDX-License-Identifier: BSD-2-Clause-Patent\r
d1f95000 10\r
d1f95000 11 @par Revision Reference: PI\r
12 Version 1.00.\r
13\r
14**/\r
15\r
16#ifndef __FIRMWARE_VOLUME2_H__\r
17#define __FIRMWARE_VOLUME2_H__\r
18\r
19#define EFI_FIRMWARE_VOLUME2_PROTOCOL_GUID \\r
22142dbf 20 { 0x220e73b6, 0x6bdb, 0x4413, { 0x84, 0x5, 0xb9, 0x74, 0xb1, 0x8, 0x61, 0x9a } }\r
d1f95000 21\r
22typedef struct _EFI_FIRMWARE_VOLUME2_PROTOCOL EFI_FIRMWARE_VOLUME2_PROTOCOL;\r
23\r
99e8ed21 24///\r
25/// EFI_FV_ATTRIBUTES\r
26///\r
2f88bd3a 27typedef UINT64 EFI_FV_ATTRIBUTES;\r
d1f95000 28\r
29//\r
30// EFI_FV_ATTRIBUTES bit definitions\r
31//\r
32// EFI_FV_ATTRIBUTES bit semantics\r
2f88bd3a
MK		 33#define EFI_FV2_READ_DISABLE_CAP 0x0000000000000001ULL\r
34#define EFI_FV2_READ_ENABLE_CAP 0x0000000000000002ULL\r
35#define EFI_FV2_READ_STATUS 0x0000000000000004ULL\r
36#define EFI_FV2_WRITE_DISABLE_CAP 0x0000000000000008ULL\r
37#define EFI_FV2_WRITE_ENABLE_CAP 0x0000000000000010ULL\r
38#define EFI_FV2_WRITE_STATUS 0x0000000000000020ULL\r
39#define EFI_FV2_LOCK_CAP 0x0000000000000040ULL\r
40#define EFI_FV2_LOCK_STATUS 0x0000000000000080ULL\r
41#define EFI_FV2_WRITE_POLICY_RELIABLE 0x0000000000000100ULL\r
42#define EFI_FV2_READ_LOCK_CAP 0x0000000000001000ULL\r
43#define EFI_FV2_READ_LOCK_STATUS 0x0000000000002000ULL\r
44#define EFI_FV2_WRITE_LOCK_CAP 0x0000000000004000ULL\r
45#define EFI_FV2_WRITE_LOCK_STATUS 0x0000000000008000ULL\r
46#define EFI_FV2_ALIGNMENT 0x00000000001F0000ULL\r
47#define EFI_FV2_ALIGNMENT_1 0x0000000000000000ULL\r
48#define EFI_FV2_ALIGNMENT_2 0x0000000000010000ULL\r
49#define EFI_FV2_ALIGNMENT_4 0x0000000000020000ULL\r
50#define EFI_FV2_ALIGNMENT_8 0x0000000000030000ULL\r
51#define EFI_FV2_ALIGNMENT_16 0x0000000000040000ULL\r
52#define EFI_FV2_ALIGNMENT_32 0x0000000000050000ULL\r
53#define EFI_FV2_ALIGNMENT_64 0x0000000000060000ULL\r
54#define EFI_FV2_ALIGNMENT_128 0x0000000000070000ULL\r
55#define EFI_FV2_ALIGNMENT_256 0x0000000000080000ULL\r
56#define EFI_FV2_ALIGNMENT_512 0x0000000000090000ULL\r
57#define EFI_FV2_ALIGNMENT_1K 0x00000000000A0000ULL\r
58#define EFI_FV2_ALIGNMENT_2K 0x00000000000B0000ULL\r
59#define EFI_FV2_ALIGNMENT_4K 0x00000000000C0000ULL\r
60#define EFI_FV2_ALIGNMENT_8K 0x00000000000D0000ULL\r
61#define EFI_FV2_ALIGNMENT_16K 0x00000000000E0000ULL\r
62#define EFI_FV2_ALIGNMENT_32K 0x00000000000F0000ULL\r
63#define EFI_FV2_ALIGNMENT_64K 0x0000000000100000ULL\r
64#define EFI_FV2_ALIGNMENT_128K 0x0000000000110000ULL\r
65#define EFI_FV2_ALIGNMENT_256K 0x0000000000120000ULL\r
66#define EFI_FV2_ALIGNMENT_512K 0x0000000000130000ULL\r
67#define EFI_FV2_ALIGNMENT_1M 0x0000000000140000ULL\r
68#define EFI_FV2_ALIGNMENT_2M 0x0000000000150000ULL\r
69#define EFI_FV2_ALIGNMENT_4M 0x0000000000160000ULL\r
70#define EFI_FV2_ALIGNMENT_8M 0x0000000000170000ULL\r
71#define EFI_FV2_ALIGNMENT_16M 0x0000000000180000ULL\r
72#define EFI_FV2_ALIGNMENT_32M 0x0000000000190000ULL\r
73#define EFI_FV2_ALIGNMENT_64M 0x00000000001A0000ULL\r
74#define EFI_FV2_ALIGNMENT_128M 0x00000000001B0000ULL\r
75#define EFI_FV2_ALIGNMENT_256M 0x00000000001C0000ULL\r
76#define EFI_FV2_ALIGNMENT_512M 0x00000000001D0000ULL\r
77#define EFI_FV2_ALIGNMENT_1G 0x00000000001E0000ULL\r
78#define EFI_FV2_ALIGNMENT_2G 0x00000000001F0000ULL\r
d1f95000 79\r
80/**\r
eecd469b
LG		 81 Returns the attributes and current settings of the firmware volume.\r
82\r
d1f95000 83 Because of constraints imposed by the underlying firmware\r
84 storage, an instance of the Firmware Volume Protocol may not\r
85 be to able to support all possible variations of this\r
86 architecture. These constraints and the current state of the\r
87 firmware volume are exposed to the caller using the\r
88 GetVolumeAttributes() function. GetVolumeAttributes() is\r
50615d1f 89 callable only from TPL_NOTIFY and below. Behavior of\r
90 GetVolumeAttributes() at any EFI_TPL above TPL_NOTIFY is\r
4ca9b6c4
LG		 91 undefined.\r
92\r
93 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
9095d37b 94\r
d1f95000 95 @param FvAttributes Pointer to an EFI_FV_ATTRIBUTES in which\r
96 the attributes and current settings are\r
97 returned.\r
98\r
99\r
100 @retval EFI_SUCCESS The firmware volume attributes were\r
101 returned.\r
102\r
103**/\r
104typedef\r
105EFI_STATUS\r
2f88bd3a 106(EFIAPI *EFI_FV_GET_ATTRIBUTES)(\r
d1f95000 107 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
108 OUT EFI_FV_ATTRIBUTES *FvAttributes\r
2f88bd3a 109 );\r
d1f95000 110\r
111/**\r
eecd469b 112 Modifies the current settings of the firmware volume according to the input parameter.\r
9095d37b 113\r
d1f95000 114 The SetVolumeAttributes() function is used to set configurable\r
115 firmware volume attributes. Only EFI_FV_READ_STATUS,\r
116 EFI_FV_WRITE_STATUS, and EFI_FV_LOCK_STATUS may be modified, and\r
117 then only in accordance with the declared capabilities. All\r
118 other bits of FvAttributes are ignored on input. On successful\r
119 return, all bits of *FvAttributes are valid and it contains the\r
120 completed EFI_FV_ATTRIBUTES for the volume. To modify an\r
121 attribute, the corresponding status bit in the EFI_FV_ATTRIBUTES\r
122 is set to the desired value on input. The EFI_FV_LOCK_STATUS bit\r
123 does not affect the ability to read or write the firmware\r
124 volume. Rather, once the EFI_FV_LOCK_STATUS bit is set, it\r
125 prevents further modification to all the attribute bits.\r
50615d1f 126 SetVolumeAttributes() is callable only from TPL_NOTIFY and\r
d1f95000 127 below. Behavior of SetVolumeAttributes() at any EFI_TPL above\r
4ca9b6c4 128 TPL_NOTIFY is undefined.\r
d1f95000 129\r
4ca9b6c4 130 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
9095d37b 131\r
d1f95000 132 @param FvAttributes On input, FvAttributes is a pointer to\r
133 an EFI_FV_ATTRIBUTES containing the\r
134 desired firmware volume settings. On\r
135 successful return, it contains the new\r
136 settings of the firmware volume. On\r
137 unsuccessful return, FvAttributes is not\r
138 modified and the firmware volume\r
139 settings are not changed.\r
9095d37b 140\r
4ca9b6c4
LG		 141 @retval EFI_SUCCESS The requested firmware volume attributes\r
142 were set and the resulting\r
143 EFI_FV_ATTRIBUTES is returned in\r
144 FvAttributes.\r
d1f95000 145\r
146 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
147 is set to 1 on input, but the\r
148 device does not support enabling\r
149 reads\r
150 (FvAttributes:EFI_FV_READ_ENABLE\r
151 is clear on return from\r
152 GetVolumeAttributes()). Actual\r
153 volume attributes are unchanged.\r
154\r
155 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_READ_STATUS\r
156 is cleared to 0 on input, but\r
157 the device does not support\r
158 disabling reads\r
159 (FvAttributes:EFI_FV_READ_DISABL\r
160 is clear on return from\r
161 GetVolumeAttributes()). Actual\r
162 volume attributes are unchanged.\r
163\r
164 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
165 is set to 1 on input, but the\r
166 device does not support enabling\r
167 writes\r
168 (FvAttributes:EFI_FV_WRITE_ENABL\r
169 is clear on return from\r
170 GetVolumeAttributes()). Actual\r
171 volume attributes are unchanged.\r
172\r
173 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_WRITE_STATUS\r
174 is cleared to 0 on input, but\r
175 the device does not support\r
176 disabling writes\r
177 (FvAttributes:EFI_FV_WRITE_DISAB\r
178 is clear on return from\r
179 GetVolumeAttributes()). Actual\r
180 volume attributes are unchanged.\r
181\r
182 @retval EFI_INVALID_PARAMETER FvAttributes:EFI_FV_LOCK_STATUS\r
183 is set on input, but the device\r
184 does not support locking\r
185 (FvAttributes:EFI_FV_LOCK_CAP is\r
186 clear on return from\r
187 GetVolumeAttributes()). Actual\r
188 volume attributes are unchanged.\r
189\r
190 @retval EFI_ACCESS_DENIED Device is locked and does not\r
191 allow attribute modification\r
192 (FvAttributes:EFI_FV_LOCK_STATUS\r
193 is set on return from\r
194 GetVolumeAttributes()). Actual\r
195 volume attributes are unchanged.\r
196\r
197**/\r
198typedef\r
199EFI_STATUS\r
2f88bd3a 200(EFIAPI *EFI_FV_SET_ATTRIBUTES)(\r
d1f95000 201 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
202 IN OUT EFI_FV_ATTRIBUTES *FvAttributes\r
2f88bd3a 203 );\r
d1f95000 204\r
205/**\r
eecd469b
LG		 206 Retrieves a file and/or file information from the firmware volume.\r
207\r
d1f95000 208 ReadFile() is used to retrieve any file from a firmware volume\r
209 during the DXE phase. The actual binary encoding of the file in\r
210 the firmware volume media may be in any arbitrary format as long\r
eecd469b
LG		 211 as it does the following: It is accessed using the Firmware\r
212 Volume Protocol. The image that is returned follows the image\r
d1f95000 213 format defined in Code Definitions: PI Firmware File Format.\r
214 If the input value of Buffer==NULL, it indicates the caller is\r
215 requesting only that the type, attributes, and size of the\r
216 file be returned and that there is no output buffer. In this\r
217 case, the following occurs:\r
218 - BufferSize is returned with the size that is required to\r
219 successfully complete the read.\r
220 - The output parameters FoundType and *FileAttributes are\r
221 returned with valid values.\r
222 - The returned value of *AuthenticationStatus is undefined.\r
223\r
224 If the input value of Buffer!=NULL, the output buffer is\r
225 specified by a double indirection of the Buffer parameter. The\r
226 input value of *Buffer is used to determine if the output\r
227 buffer is caller allocated or is dynamically allocated by\r
228 ReadFile(). If the input value of *Buffer!=NULL, it indicates\r
229 the output buffer is caller allocated. In this case, the input\r
230 value of *BufferSize indicates the size of the\r
231 caller-allocated output buffer. If the output buffer is not\r
232 large enough to contain the entire requested output, it is\r
233 filled up to the point that the output buffer is exhausted and\r
234 EFI_WARN_BUFFER_TOO_SMALL is returned, and then BufferSize is\r
235 returned with the size required to successfully complete the\r
236 read. All other output parameters are returned with valid\r
237 values. If the input value of *Buffer==NULL, it indicates the\r
238 output buffer is to be allocated by ReadFile(). In this case,\r
239 ReadFile() will allocate an appropriately sized buffer from\r
240 boot services pool memory, which will be returned in Buffer.\r
241 The size of the new buffer is returned in BufferSize and all\r
242 other output parameters are returned with valid values.\r
50615d1f 243 ReadFile() is callable only from TPL_NOTIFY and below.\r
244 Behavior of ReadFile() at any EFI_TPL above TPL_NOTIFY is\r
4ca9b6c4
LG		 245 undefined.\r
246\r
247 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
9095d37b 248\r
4ca9b6c4
LG		 249 @param NameGuid Pointer to an EFI_GUID, which is the file\r
250 name. All firmware file names are EFI_GUIDs.\r
251 A single firmware volume must not have two\r
252 valid files with the same file name\r
253 EFI_GUID.\r
9095d37b 254\r
4ca9b6c4
LG		 255 @param Buffer Pointer to a pointer to a buffer in which the\r
256 file contents are returned, not including the\r
257 file header.\r
258\r
259 @param BufferSize Pointer to a caller-allocated UINTN. It\r
260 indicates the size of the memory\r
261 represented by Buffer.\r
9095d37b 262\r
4ca9b6c4 263 @param FoundType Pointer to a caller-allocated EFI_FV_FILETYPE.\r
9095d37b 264\r
4ca9b6c4
LG		 265 @param FileAttributes Pointer to a caller-allocated\r
266 EFI_FV_FILE_ATTRIBUTES.\r
9095d37b 267\r
d1f95000 268 @param AuthenticationStatus Pointer to a caller-allocated\r
269 UINT32 in which the\r
270 authentication status is\r
271 returned.\r
9095d37b 272\r
4ca9b6c4 273 @retval EFI_SUCCESS The call completed successfully.\r
9095d37b 274\r
d1f95000 275 @retval EFI_WARN_BUFFER_TOO_SMALL The buffer is too small to\r
276 contain the requested\r
277 output. The buffer is\r
278 filled and the output is\r
279 truncated.\r
280\r
4ca9b6c4 281 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
d1f95000 282\r
4ca9b6c4 283 @retval EFI_NOT_FOUND Name was not found in the firmware volume.\r
d1f95000 284\r
4ca9b6c4
LG		 285 @retval EFI_DEVICE_ERROR A hardware error occurred when\r
286 attempting to access the firmware volume.\r
d1f95000 287\r
4ca9b6c4 288 @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
630b4187 289 disallow reads.\r
d1f95000 290\r
291**/\r
292typedef\r
293EFI_STATUS\r
2f88bd3a 294(EFIAPI *EFI_FV_READ_FILE)(\r
d1f95000 295 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
296 IN CONST EFI_GUID *NameGuid,\r
297 IN OUT VOID **Buffer,\r
298 IN OUT UINTN *BufferSize,\r
299 OUT EFI_FV_FILETYPE *FoundType,\r
300 OUT EFI_FV_FILE_ATTRIBUTES *FileAttributes,\r
301 OUT UINT32 *AuthenticationStatus\r
2f88bd3a 302 );\r
d1f95000 303\r
304/**\r
eecd469b
LG		 305 Locates the requested section within a file and returns it in a buffer.\r
306\r
d1f95000 307 ReadSection() is used to retrieve a specific section from a file\r
308 within a firmware volume. The section returned is determined\r
309 using a depth-first, left-to-right search algorithm through all\r
eecd469b 310 sections found in the specified file. The output buffer is specified by a double indirection\r
d1f95000 311 of the Buffer parameter. The input value of Buffer is used to\r
312 determine if the output buffer is caller allocated or is\r
313 dynamically allocated by ReadSection(). If the input value of\r
314 Buffer!=NULL, it indicates that the output buffer is caller\r
315 allocated. In this case, the input value of *BufferSize\r
316 indicates the size of the caller-allocated output buffer. If\r
317 the output buffer is not large enough to contain the entire\r
318 requested output, it is filled up to the point that the output\r
319 buffer is exhausted and EFI_WARN_BUFFER_TOO_SMALL is returned,\r
320 and then BufferSize is returned with the size that is required\r
321 to successfully complete the read. All other\r
322 output parameters are returned with valid values. If the input\r
323 value of *Buffer==NULL, it indicates the output buffer is to\r
324 be allocated by ReadSection(). In this case, ReadSection()\r
325 will allocate an appropriately sized buffer from boot services\r
326 pool memory, which will be returned in *Buffer. The size of\r
327 the new buffer is returned in *BufferSize and all other output\r
328 parameters are returned with valid values. ReadSection() is\r
50615d1f 329 callable only from TPL_NOTIFY and below. Behavior of\r
330 ReadSection() at any EFI_TPL above TPL_NOTIFY is\r
4ca9b6c4
LG		 331 undefined.\r
332\r
333 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
9095d37b 334\r
4ca9b6c4
LG		 335 @param NameGuid Pointer to an EFI_GUID, which indicates the\r
336 file name from which the requested section\r
337 will be read.\r
9095d37b 338\r
4ca9b6c4
LG		 339 @param SectionType Indicates the section type to return.\r
340 SectionType in conjunction with\r
341 SectionInstance indicates which section to\r
342 return.\r
9095d37b 343\r
4ca9b6c4
LG		 344 @param SectionInstance Indicates which instance of sections\r
345 with a type of SectionType to return.\r
346 SectionType in conjunction with\r
347 SectionInstance indicates which\r
348 section to return. SectionInstance is\r
349 zero based.\r
9095d37b 350\r
4ca9b6c4
LG		 351 @param Buffer Pointer to a pointer to a buffer in which the\r
352 section contents are returned, not including\r
353 the section header.\r
9095d37b 354\r
4ca9b6c4
LG		 355 @param BufferSize Pointer to a caller-allocated UINTN. It\r
356 indicates the size of the memory\r
357 represented by Buffer.\r
9095d37b 358\r
d1f95000 359 @param AuthenticationStatus Pointer to a caller-allocated\r
360 UINT32 in which the authentication\r
361 status is returned.\r
9095d37b
LG		 362\r
363\r
d1f95000 364 @retval EFI_SUCCESS The call completed successfully.\r
9095d37b 365\r
d1f95000 366 @retval EFI_WARN_BUFFER_TOO_SMALL The caller-allocated\r
367 buffer is too small to\r
368 contain the requested\r
369 output. The buffer is\r
370 filled and the output is\r
371 truncated.\r
9095d37b 372\r
d1f95000 373 @retval EFI_OUT_OF_RESOURCES An allocation failure occurred.\r
9095d37b 374\r
d1f95000 375 @retval EFI_NOT_FOUND The requested file was not found in\r
376 the firmware volume. EFI_NOT_FOUND The\r
377 requested section was not found in the\r
378 specified file.\r
9095d37b 379\r
d1f95000 380 @retval EFI_DEVICE_ERROR A hardware error occurred when\r
381 attempting to access the firmware\r
382 volume.\r
9095d37b 383\r
d1f95000 384 @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
385 disallow reads. EFI_PROTOCOL_ERROR\r
386 The requested section was not found,\r
387 but the file could not be fully\r
388 parsed because a required\r
389 GUIDED_SECTION_EXTRACTION_PROTOCOL\r
390 was not found. It is possible the\r
391 requested section exists within the\r
392 file and could be successfully\r
393 extracted once the required\r
394 GUIDED_SECTION_EXTRACTION_PROTOCOL\r
395 is published.\r
396\r
397**/\r
398typedef\r
399EFI_STATUS\r
2f88bd3a 400(EFIAPI *EFI_FV_READ_SECTION)(\r
d1f95000 401 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
402 IN CONST EFI_GUID *NameGuid,\r
de339b9d 403 IN EFI_SECTION_TYPE SectionType,\r
404 IN UINTN SectionInstance,\r
d1f95000 405 IN OUT VOID **Buffer,\r
406 IN OUT UINTN *BufferSize,\r
407 OUT UINT32 *AuthenticationStatus\r
2f88bd3a 408 );\r
d1f95000 409\r
992f22b9
LG		 410///\r
411/// EFI_FV_WRITE_POLICY, two policies (unreliable write and reliable write) are defined.\r
412///\r
d1f95000 413typedef UINT32 EFI_FV_WRITE_POLICY;\r
2f88bd3a
MK		 414#define EFI_FV_UNRELIABLE_WRITE 0x00000000\r
415#define EFI_FV_RELIABLE_WRITE 0x00000001\r
d1f95000 416\r
417//\r
418// EFI_FV_WRITE_FILE_DATA\r
419//\r
420typedef struct {\r
74fec708
LG		 421 ///\r
422 /// Pointer to a GUID, which is the file name to be written.\r
423 ///\r
2f88bd3a 424 EFI_GUID *NameGuid;\r
74fec708
LG		 425 ///\r
426 /// Indicates the type of file to be written.\r
427 ///\r
2f88bd3a 428 EFI_FV_FILETYPE Type;\r
74fec708
LG		 429 ///\r
430 /// Indicates the attributes for the file to be written.\r
431 ///\r
2f88bd3a 432 EFI_FV_FILE_ATTRIBUTES FileAttributes;\r
74fec708
LG		 433 ///\r
434 /// Pointer to a buffer containing the file to be written.\r
435 ///\r
2f88bd3a 436 VOID *Buffer;\r
74fec708
LG		 437 ///\r
438 /// Indicates the size of the file image contained in Buffer.\r
439 ///\r
2f88bd3a 440 UINT32 BufferSize;\r
d1f95000 441} EFI_FV_WRITE_FILE_DATA;\r
442\r
443/**\r
eecd469b
LG		 444 Locates the requested section within a file and returns it in a buffer.\r
445\r
d1f95000 446 WriteFile() is used to write one or more files to a firmware\r
447 volume. Each file to be written is described by an\r
448 EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that\r
449 any required alignment for all files listed in the FileData\r
450 array is compatible with the firmware volume. Firmware volume\r
451 capabilities can be determined using the GetVolumeAttributes()\r
452 call. Similarly, if the WritePolicy is set to\r
453 EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume\r
454 capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the\r
455 firmware volume. EFI_FV_UNRELIABLE_WRITE must always be\r
456 supported. Writing a file with a size of zero\r
457 (FileData[n].BufferSize == 0) deletes the file from the firmware\r
458 volume if it exists. Deleting a file must be done one at a time.\r
459 Deleting a file as part of a multiple file write is not allowed.\r
460 Platform Initialization Specification VOLUME 3 Shared\r
461 Architectural Elements 84 August 21, 2006 Version 1.0\r
50615d1f 462 WriteFile() is callable only from TPL_NOTIFY and below.\r
463 Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is\r
9095d37b 464 undefined.\r
d1f95000 465\r
4ca9b6c4 466 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
d1f95000 467\r
4ca9b6c4 468 @param NumberOfFiles Indicates the number of elements in the array pointed to by FileData\r
d1f95000 469\r
4ca9b6c4
LG		 470 @param WritePolicy Indicates the level of reliability for the\r
471 write in the event of a power failure or\r
472 other system failure during the write\r
473 operation.\r
9095d37b 474\r
4ca9b6c4
LG		 475 @param FileData Pointer to an array of\r
476 EFI_FV_WRITE_FILE_DATA. Each element of\r
477 FileData[] represents a file to be written.\r
d1f95000 478\r
479\r
4ca9b6c4 480 @retval EFI_SUCCESS The write completed successfully.\r
9095d37b 481\r
4ca9b6c4
LG		 482 @retval EFI_OUT_OF_RESOURCES The firmware volume does not\r
483 have enough free space to\r
484 storefile(s).\r
9095d37b 485\r
4ca9b6c4
LG		 486 @retval EFI_DEVICE_ERROR A hardware error occurred when\r
487 attempting to access the firmware volume.\r
9095d37b 488\r
4ca9b6c4
LG		 489 @retval EFI_WRITE_PROTECTED The firmware volume is\r
490 configured to disallow writes.\r
9095d37b 491\r
4ca9b6c4
LG		 492 @retval EFI_NOT_FOUND A delete was requested, but the\r
493 requested file was not found in the\r
494 firmware volume.\r
9095d37b 495\r
d1f95000 496 @retval EFI_INVALID_PARAMETER A delete was requested with a\r
497 multiple file write.\r
9095d37b 498\r
d1f95000 499 @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was\r
500 requested.\r
501\r
502 @retval EFI_INVALID_PARAMETER An unknown file type was\r
503 specified.\r
504\r
505 @retval EFI_INVALID_PARAMETER A file system specific error\r
506 has occurred.\r
9095d37b 507\r
d1f95000 508**/\r
509typedef\r
9095d37b 510EFI_STATUS\r
2f88bd3a 511(EFIAPI *EFI_FV_WRITE_FILE)(\r
d1f95000 512 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
4bad02f2 513 IN UINT32 NumberOfFiles,\r
514 IN EFI_FV_WRITE_POLICY WritePolicy,\r
515 IN EFI_FV_WRITE_FILE_DATA *FileData\r
2f88bd3a 516 );\r
d1f95000 517\r
518/**\r
9095d37b 519 Retrieves information about the next file in the firmware volume store\r
ee6c452c 520 that matches the search criteria.\r
eecd469b 521\r
d1f95000 522 GetNextFile() is the interface that is used to search a firmware\r
523 volume for a particular file. It is called successively until\r
524 the desired file is located or the function returns\r
525 EFI_NOT_FOUND. To filter uninteresting files from the output,\r
526 the type of file to search for may be specified in FileType. For\r
527 example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of\r
528 this type will be returned in the output. If *FileType is\r
529 EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key\r
530 parameter is used to indicate a starting point of the search. If\r
531 the buffer *Key is completely initialized to zero, the search\r
532 re-initialized and starts at the beginning. Subsequent calls to\r
533 GetNextFile() must maintain the value of *Key returned by the\r
534 immediately previous call. The actual contents of *Key are\r
535 implementation specific and no semantic content is implied.\r
50615d1f 536 GetNextFile() is callable only from TPL_NOTIFY and below.\r
537 Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is\r
9095d37b 538 undefined.\r
4ca9b6c4
LG		 539\r
540 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.\r
541\r
542 @param Key Pointer to a caller-allocated buffer that contains implementation-specific data that is\r
543 used to track where to begin the search for the next file. The size of the buffer must be\r
544 at least This->KeySize bytes long. To re-initialize the search and begin from the\r
545 beginning of the firmware volume, the entire buffer must be cleared to zero. Other\r
546 than clearing the buffer to initiate a new search, the caller must not modify the data in\r
547 the buffer between calls to GetNextFile().\r
d1f95000 548\r
549 @param FileType Pointer to a caller-allocated\r
550 EFI_FV_FILETYPE. The GetNextFile() API can\r
551 filter its search for files based on the\r
552 value of the FileType input. A *FileType\r
553 input of EFI_FV_FILETYPE_ALL causes\r
554 GetNextFile() to search for files of all\r
555 types. If a file is found, the file's type\r
556 is returned in FileType. *FileType is not\r
557 modified if no file is found.\r
558\r
559 @param NameGuid Pointer to a caller-allocated EFI_GUID. If a\r
560 matching file is found, the file's name is\r
561 returned in NameGuid. If no matching file is\r
562 found, *NameGuid is not modified.\r
563\r
564 @param Attributes Pointer to a caller-allocated\r
565 EFI_FV_FILE_ATTRIBUTES. If a matching file\r
566 is found, the file's attributes are returned\r
567 in Attributes. If no matching file is found,\r
568 Attributes is not modified. Type\r
569 EFI_FV_FILE_ATTRIBUTES is defined in\r
570 ReadFile().\r
571\r
4ca9b6c4
LG		 572 @param Size Pointer to a caller-allocated UINTN. If a\r
573 matching file is found, the file's size is\r
574 returned in *Size. If no matching file is found,\r
575 Size is not modified.\r
d1f95000 576\r
4ca9b6c4
LG		 577 @retval EFI_SUCCESS The output parameters are filled with data\r
578 obtained from the first matching file that\r
579 was found.\r
d1f95000 580\r
4ca9b6c4 581 @retval FI_NOT_FOUND No files of type FileType were found.\r
d1f95000 582\r
583\r
584 @retval EFI_DEVICE_ERROR A hardware error occurred when\r
585 attempting to access the firmware\r
586 volume.\r
587\r
588 @retval EFI_ACCESS_DENIED The firmware volume is configured to\r
589 disallow reads.\r
590\r
9095d37b 591\r
d1f95000 592**/\r
593typedef\r
594EFI_STATUS\r
2f88bd3a 595(EFIAPI *EFI_FV_GET_NEXT_FILE)(\r
d1f95000 596 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
597 IN OUT VOID *Key,\r
598 IN OUT EFI_FV_FILETYPE *FileType,\r
599 OUT EFI_GUID *NameGuid,\r
600 OUT EFI_FV_FILE_ATTRIBUTES *Attributes,\r
601 OUT UINTN *Size\r
2f88bd3a 602 );\r
d1f95000 603\r
604/**\r
eecd469b
LG		 605 Return information about a firmware volume.\r
606\r
d1f95000 607 The GetInfo() function returns information of type\r
608 InformationType for the requested firmware volume. If the volume\r
609 does not support the requested information type, then\r
610 EFI_UNSUPPORTED is returned. If the buffer is not large enough\r
611 to hold the requested structure, EFI_BUFFER_TOO_SMALL is\r
612 returned and the BufferSize is set to the size of buffer that is\r
613 required to make the request. The information types defined by\r
614 this specification are required information types that all file\r
615 systems must support.\r
616\r
4ca9b6c4
LG		 617 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
618 instance that is the file handle the requested\r
619 information is for.\r
9095d37b 620\r
d1f95000 621 @param InformationType The type identifier for the\r
622 information being requested.\r
9095d37b 623\r
4ca9b6c4
LG		 624 @param BufferSize On input, the size of Buffer. On output,\r
625 the amount of data returned in Buffer. In\r
626 both cases, the size is measured in bytes.\r
9095d37b 627\r
4ca9b6c4
LG		 628 @param Buffer A pointer to the data buffer to return. The\r
629 buffer's type is indicated by InformationType.\r
9095d37b
LG		 630\r
631\r
4ca9b6c4 632 @retval EFI_SUCCESS The information was retrieved.\r
9095d37b 633\r
4ca9b6c4 634 @retval EFI_UNSUPPORTED The InformationType is not known.\r
9095d37b 635\r
4ca9b6c4 636 @retval EFI_NO_MEDIA The device has no medium.\r
9095d37b 637\r
4ca9b6c4 638 @retval EFI_DEVICE_ERROR The device reported an error.\r
9095d37b 639\r
d1f95000 640 @retval EFI_VOLUME_CORRUPTED The file system structures are\r
641 corrupted.\r
9095d37b 642\r
d1f95000 643 @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to\r
644 read the current directory\r
645 entry. BufferSize has been\r
646 updated with the size needed to\r
647 complete the request.\r
648\r
649\r
650**/\r
651typedef\r
652EFI_STATUS\r
8b13229b 653(EFIAPI *EFI_FV_GET_INFO)(\r
d1f95000 654 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
655 IN CONST EFI_GUID *InformationType,\r
656 IN OUT UINTN *BufferSize,\r
657 OUT VOID *Buffer\r
2f88bd3a 658 );\r
d1f95000 659\r
660/**\r
eecd469b 661 Sets information about a firmware volume.\r
d1f95000 662\r
663 The SetInfo() function sets information of type InformationType\r
664 on the requested firmware volume.\r
665\r
666\r
4ca9b6c4
LG		 667 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL\r
668 instance that is the file handle the information\r
669 is for.\r
d1f95000 670\r
671 @param InformationType The type identifier for the\r
672 information being set.\r
673\r
4ca9b6c4 674 @param BufferSize The size, in bytes, of Buffer.\r
d1f95000 675\r
4ca9b6c4
LG		 676 @param Buffer A pointer to the data buffer to write. The\r
677 buffer's type is indicated by InformationType.\r
d1f95000 678\r
4ca9b6c4 679 @retval EFI_SUCCESS The information was set.\r
d1f95000 680\r
4ca9b6c4 681 @retval EFI_UNSUPPORTED The InformationType is not known.\r
d1f95000 682\r
4ca9b6c4 683 @retval EFI_NO_MEDIA The device has no medium.\r
d1f95000 684\r
4ca9b6c4 685 @retval EFI_DEVICE_ERROR The device reported an error.\r
d1f95000 686\r
687 @retval EFI_VOLUME_CORRUPTED The file system structures are\r
688 corrupted.\r
689\r
690\r
4ca9b6c4 691 @retval EFI_WRITE_PROTECTED The media is read only.\r
d1f95000 692\r
4ca9b6c4 693 @retval EFI_VOLUME_FULL The volume is full.\r
d1f95000 694\r
4ca9b6c4
LG		 695 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the\r
696 size of the type indicated by\r
697 InformationType.\r
d1f95000 698\r
699**/\r
700typedef\r
701EFI_STATUS\r
8b13229b 702(EFIAPI *EFI_FV_SET_INFO)(\r
d1f95000 703 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,\r
704 IN CONST EFI_GUID *InformationType,\r
705 IN UINTN BufferSize,\r
706 IN CONST VOID *Buffer\r
2f88bd3a 707 );\r
d1f95000 708\r
44717a39 709///\r
710/// The Firmware Volume Protocol contains the file-level\r
711/// abstraction to the firmware volume as well as some firmware\r
712/// volume attribute reporting and configuration services. The\r
713/// Firmware Volume Protocol is the interface used by all parts of\r
714/// DXE that are not directly involved with managing the firmware\r
715/// volume itself. This abstraction allows many varied types of\r
716/// firmware volume implementations. A firmware volume may be a\r
717/// flash device or it may be a file in the UEFI system partition,\r
718/// for example. This level of firmware volume implementation\r
719/// detail is not visible to the consumers of the Firmware Volume\r
720/// Protocol.\r
721///\r
d1f95000 722struct _EFI_FIRMWARE_VOLUME2_PROTOCOL {\r
2f88bd3a
MK		 723 EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;\r
724 EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;\r
725 EFI_FV_READ_FILE ReadFile;\r
726 EFI_FV_READ_SECTION ReadSection;\r
727 EFI_FV_WRITE_FILE WriteFile;\r
728 EFI_FV_GET_NEXT_FILE GetNextFile;\r
9095d37b 729\r
a4e0b060 730 ///\r
731 /// Data field that indicates the size in bytes\r
732 /// of the Key input buffer for the\r
9095d37b 733 /// GetNextFile() API.\r
a4e0b060 734 ///\r
2f88bd3a 735 UINT32 KeySize;\r
9095d37b 736\r
a4e0b060 737 ///\r
738 /// Handle of the parent firmware volume.\r
739 ///\r
2f88bd3a
MK		 740 EFI_HANDLE ParentHandle;\r
741 EFI_FV_GET_INFO GetInfo;\r
742 EFI_FV_SET_INFO SetInfo;\r
d1f95000 743};\r
744\r
2f88bd3a 745extern EFI_GUID gEfiFirmwareVolume2ProtocolGuid;\r
d1f95000 746\r
747#endif\r
EFI Development Kit II mirror for PVE