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