]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/FirmwareVolume2.h
projects / mirror_edk2.git / blob
? search:


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