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