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


62218d71497e675f553ef1edbbc86f4fa3abb16a
[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
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 EFI_GUID *NameGuid;
433 EFI_FV_FILETYPE Type;
434 EFI_FV_FILE_ATTRIBUTES FileAttributes;
435 VOID *Buffer;
436 UINT32 BufferSize;
437 } EFI_FV_WRITE_FILE_DATA;
438
439 /**
440 Locates the requested section within a file and returns it in a buffer.
441
442 WriteFile() is used to write one or more files to a firmware
443 volume. Each file to be written is described by an
444 EFI_FV_WRITE_FILE_DATA structure. The caller must ensure that
445 any required alignment for all files listed in the FileData
446 array is compatible with the firmware volume. Firmware volume
447 capabilities can be determined using the GetVolumeAttributes()
448 call. Similarly, if the WritePolicy is set to
449 EFI_FV_RELIABLE_WRITE, the caller must check the firmware volume
450 capabilities to ensure EFI_FV_RELIABLE_WRITE is supported by the
451 firmware volume. EFI_FV_UNRELIABLE_WRITE must always be
452 supported. Writing a file with a size of zero
453 (FileData[n].BufferSize == 0) deletes the file from the firmware
454 volume if it exists. Deleting a file must be done one at a time.
455 Deleting a file as part of a multiple file write is not allowed.
456 Platform Initialization Specification VOLUME 3 Shared
457 Architectural Elements 84 August 21, 2006 Version 1.0
458 WriteFile() is callable only from TPL_NOTIFY and below.
459 Behavior of WriteFile() at any EFI_TPL above TPL_NOTIFY is
460 undefined.
461
462 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
463
464 @param NumberOfFiles Indicates the number of elements in the array pointed to by FileData
465
466 @param WritePolicy Indicates the level of reliability for the
467 write in the event of a power failure or
468 other system failure during the write
469 operation.
470
471 @param FileData Pointer to an array of
472 EFI_FV_WRITE_FILE_DATA. Each element of
473 FileData[] represents a file to be written.
474
475
476 @retval EFI_SUCCESS The write completed successfully.
477
478 @retval EFI_OUT_OF_RESOURCES The firmware volume does not
479 have enough free space to
480 storefile(s).
481
482 @retval EFI_DEVICE_ERROR A hardware error occurred when
483 attempting to access the firmware volume.
484
485 @retval EFI_WRITE_PROTECTED The firmware volume is
486 configured to disallow writes.
487
488 @retval EFI_NOT_FOUND A delete was requested, but the
489 requested file was not found in the
490 firmware volume.
491
492 @retval EFI_INVALID_PARAMETER A delete was requested with a
493 multiple file write.
494
495 @retval EFI_INVALID_PARAMETER An unsupported WritePolicy was
496 requested.
497
498 @retval EFI_INVALID_PARAMETER An unknown file type was
499 specified.
500
501 @retval EFI_INVALID_PARAMETER A file system specific error
502 has occurred.
503
504 **/
505 typedef
506 EFI_STATUS
507 (EFIAPI * EFI_FV_WRITE_FILE)(
508 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
509 IN UINT32 NumberOfFiles,
510 IN EFI_FV_WRITE_POLICY WritePolicy,
511 IN EFI_FV_WRITE_FILE_DATA *FileData
512 );
513
514
515 /**
516 Retrieves information about the next file in the firmware volume store
517 that matches the search criteria.
518
519 GetNextFile() is the interface that is used to search a firmware
520 volume for a particular file. It is called successively until
521 the desired file is located or the function returns
522 EFI_NOT_FOUND. To filter uninteresting files from the output,
523 the type of file to search for may be specified in FileType. For
524 example, if *FileType is EFI_FV_FILETYPE_DRIVER, only files of
525 this type will be returned in the output. If *FileType is
526 EFI_FV_FILETYPE_ALL, no filtering of file types is done. The Key
527 parameter is used to indicate a starting point of the search. If
528 the buffer *Key is completely initialized to zero, the search
529 re-initialized and starts at the beginning. Subsequent calls to
530 GetNextFile() must maintain the value of *Key returned by the
531 immediately previous call. The actual contents of *Key are
532 implementation specific and no semantic content is implied.
533 GetNextFile() is callable only from TPL_NOTIFY and below.
534 Behavior of GetNextFile() at any EFI_TPL above TPL_NOTIFY is
535 undefined.
536
537 @param This Indicates the EFI_FIRMWARE_VOLUME2_PROTOCOL instance.
538
539 @param Key Pointer to a caller-allocated buffer that contains implementation-specific data that is
540 used to track where to begin the search for the next file. The size of the buffer must be
541 at least This->KeySize bytes long. To re-initialize the search and begin from the
542 beginning of the firmware volume, the entire buffer must be cleared to zero. Other
543 than clearing the buffer to initiate a new search, the caller must not modify the data in
544 the buffer between calls to GetNextFile().
545
546 @param FileType Pointer to a caller-allocated
547 EFI_FV_FILETYPE. The GetNextFile() API can
548 filter its search for files based on the
549 value of the FileType input. A *FileType
550 input of EFI_FV_FILETYPE_ALL causes
551 GetNextFile() to search for files of all
552 types. If a file is found, the file's type
553 is returned in FileType. *FileType is not
554 modified if no file is found.
555
556 @param NameGuid Pointer to a caller-allocated EFI_GUID. If a
557 matching file is found, the file's name is
558 returned in NameGuid. If no matching file is
559 found, *NameGuid is not modified.
560
561 @param Attributes Pointer to a caller-allocated
562 EFI_FV_FILE_ATTRIBUTES. If a matching file
563 is found, the file's attributes are returned
564 in Attributes. If no matching file is found,
565 Attributes is not modified. Type
566 EFI_FV_FILE_ATTRIBUTES is defined in
567 ReadFile().
568
569 @param Size Pointer to a caller-allocated UINTN. If a
570 matching file is found, the file's size is
571 returned in *Size. If no matching file is found,
572 Size is not modified.
573
574 @retval EFI_SUCCESS The output parameters are filled with data
575 obtained from the first matching file that
576 was found.
577
578 @retval FI_NOT_FOUND No files of type FileType were found.
579
580
581 @retval EFI_DEVICE_ERROR A hardware error occurred when
582 attempting to access the firmware
583 volume.
584
585 @retval EFI_ACCESS_DENIED The firmware volume is configured to
586 disallow reads.
587
588
589 **/
590 typedef
591 EFI_STATUS
592 (EFIAPI * EFI_FV_GET_NEXT_FILE)(
593 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
594 IN OUT VOID *Key,
595 IN OUT EFI_FV_FILETYPE *FileType,
596 OUT EFI_GUID *NameGuid,
597 OUT EFI_FV_FILE_ATTRIBUTES *Attributes,
598 OUT UINTN *Size
599 );
600
601 /**
602 Return information about a firmware volume.
603
604 The GetInfo() function returns information of type
605 InformationType for the requested firmware volume. If the volume
606 does not support the requested information type, then
607 EFI_UNSUPPORTED is returned. If the buffer is not large enough
608 to hold the requested structure, EFI_BUFFER_TOO_SMALL is
609 returned and the BufferSize is set to the size of buffer that is
610 required to make the request. The information types defined by
611 this specification are required information types that all file
612 systems must support.
613
614 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
615 instance that is the file handle the requested
616 information is for.
617
618 @param InformationType The type identifier for the
619 information being requested.
620
621 @param BufferSize On input, the size of Buffer. On output,
622 the amount of data returned in Buffer. In
623 both cases, the size is measured in bytes.
624
625 @param Buffer A pointer to the data buffer to return. The
626 buffer's type is indicated by InformationType.
627
628
629 @retval EFI_SUCCESS The information was retrieved.
630
631 @retval EFI_UNSUPPORTED The InformationType is not known.
632
633 @retval EFI_NO_MEDIA The device has no medium.
634
635 @retval EFI_DEVICE_ERROR The device reported an error.
636
637 @retval EFI_VOLUME_CORRUPTED The file system structures are
638 corrupted.
639
640 @retval EFI_BUFFER_TOO_SMALL The BufferSize is too small to
641 read the current directory
642 entry. BufferSize has been
643 updated with the size needed to
644 complete the request.
645
646
647 **/
648 typedef
649 EFI_STATUS
650 (EFIAPI *EFI_FV_GET_INFO)(
651 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
652 IN CONST EFI_GUID *InformationType,
653 IN OUT UINTN *BufferSize,
654 OUT VOID *Buffer
655 );
656
657
658 /**
659 Sets information about a firmware volume.
660
661 The SetInfo() function sets information of type InformationType
662 on the requested firmware volume.
663
664
665 @param This A pointer to the EFI_FIRMWARE_VOLUME2_PROTOCOL
666 instance that is the file handle the information
667 is for.
668
669 @param InformationType The type identifier for the
670 information being set.
671
672 @param BufferSize The size, in bytes, of Buffer.
673
674 @param Buffer A pointer to the data buffer to write. The
675 buffer's type is indicated by InformationType.
676
677 @retval EFI_SUCCESS The information was set.
678
679 @retval EFI_UNSUPPORTED The InformationType is not known.
680
681 @retval EFI_NO_MEDIA The device has no medium.
682
683 @retval EFI_DEVICE_ERROR The device reported an error.
684
685 @retval EFI_VOLUME_CORRUPTED The file system structures are
686 corrupted.
687
688
689 @retval EFI_WRITE_PROTECTED The media is read only.
690
691 @retval EFI_VOLUME_FULL The volume is full.
692
693 @retval EFI_BAD_BUFFER_SIZE BufferSize is smaller than the
694 size of the type indicated by
695 InformationType.
696
697 **/
698 typedef
699 EFI_STATUS
700 (EFIAPI *EFI_FV_SET_INFO)(
701 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
702 IN CONST EFI_GUID *InformationType,
703 IN UINTN BufferSize,
704 IN CONST VOID *Buffer
705 );
706
707
708 /**
709 @par Protocol Description:
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 **/
722 struct _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
745
746 extern EFI_GUID gEfiFirmwareVolume2ProtocolGuid;
747
748 #endif
EFI Development Kit II mirror for PVE