VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/Firmware/MdePkg/Include/Protocol/FirmwareVolume2.h

最後變更 在這個檔案是 99404,由 vboxsync 提交於 2 年 前

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

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette