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