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