]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Ppi/FirmwareVolume.h
MdePkg: Clean up source files
[mirror_edk2.git] / MdePkg / Include / Ppi / FirmwareVolume.h
CommitLineData
c311f86b 1/** @file\r
5879b875 2 This file provides functions for accessing a memory-mapped firmware volume of a specific format.\r
3\r
9095d37b
LG
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
5 This program and the accompanying materials\r
6 are licensed and made available under the terms and conditions of the BSD License\r
7 which accompanies this distribution. The full text of the license may be found at\r
8 http://opensource.org/licenses/bsd-license.php\r
5879b875 9\r
9095d37b
LG
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
5879b875 12\r
5879b875 13 @par Revision Reference:\r
44218d2e 14 This PPI is from PI Version 1.0 errata.\r
5879b875 15\r
16**/\r
17\r
18#ifndef __FIRMWARE_VOLUME_PPI_H__\r
19#define __FIRMWARE_VOLUME_PPI_H__\r
20\r
06889842 21///\r
22/// The GUID for this PPI is the same as the firmware volume format GUID.\r
dafa11b1 23/// The FV format can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined\r
24/// format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.\r
9095d37b 25///\r
00edb218 26typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI EFI_PEI_FIRMWARE_VOLUME_PPI;\r
5879b875 27\r
28\r
29/**\r
d7132512
LG
30 Process a firmware volume and create a volume handle.\r
31\r
5879b875 32 Create a volume handle from the information in the buffer. For\r
33 memory-mapped firmware volumes, Buffer and BufferSize refer to\r
34 the start of the firmware volume and the firmware volume size.\r
35 For non memory-mapped firmware volumes, this points to a\r
36 buffer which contains the necessary information for creating\r
37 the firmware volume handle. Normally, these values are derived\r
38 from the EFI_FIRMWARE_VOLUME_INFO_PPI.\r
9095d37b
LG
39\r
40\r
dafa11b1 41 @param This Points to this instance of the\r
42 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
43 @param Buffer Points to the start of the buffer.\r
44 @param BufferSize Size of the buffer.\r
45 @param FvHandle Points to the returned firmware volume\r
46 handle. The firmware volume handle must\r
9095d37b 47 be unique within the system.\r
5879b875 48\r
dafa11b1 49 @retval EFI_SUCCESS Firmware volume handle created.\r
00edb218 50 @retval EFI_VOLUME_CORRUPTED Volume was corrupt.\r
5879b875 51\r
52**/\r
53typedef\r
54EFI_STATUS\r
8b13229b 55(EFIAPI *EFI_PEI_FV_PROCESS_FV)(\r
dafa11b1 56 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
57 IN VOID *Buffer,\r
58 IN UINTN BufferSize,\r
59 OUT EFI_PEI_FV_HANDLE *FvHandle\r
5879b875 60);\r
61\r
5879b875 62/**\r
d7132512 63 Finds the next file of the specified type.\r
5879b875 64\r
9095d37b 65 This service enables PEI modules to discover additional firmware files.\r
d7132512 66 The FileHandle must be unique within the system.\r
5879b875 67\r
dafa11b1 68 @param This Points to this instance of the\r
69 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
70 @param SearchType A filter to find only files of this type. Type\r
71 EFI_FV_FILETYPE_ALL causes no filtering to be\r
72 done.\r
73 @param FvHandle Handle of firmware volume in which to\r
74 search.\r
75 @param FileHandle Points to the current handle from which to\r
76 begin searching or NULL to start at the\r
77 beginning of the firmware volume. Updated\r
78 upon return to reflect the file found.\r
5879b875 79\r
00edb218 80 @retval EFI_SUCCESS The file was found.\r
d7132512 81 @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.\r
dafa11b1 82\r
9095d37b 83**/\r
dafa11b1 84typedef\r
85EFI_STATUS\r
9095d37b
LG
86(EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE)(\r
87 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
88 IN EFI_FV_FILETYPE SearchType,\r
dafa11b1 89 IN EFI_PEI_FV_HANDLE FvHandle,\r
9095d37b 90 IN OUT EFI_PEI_FILE_HANDLE *FileHandle\r
5879b875 91);\r
92\r
93\r
94/**\r
9095d37b
LG
95 Find a file within a volume by its name.\r
96\r
00edb218
A
97 This service searches for files with a specific name, within\r
98 either the specified firmware volume or all firmware volumes.\r
5879b875 99\r
dafa11b1 100 @param This Points to this instance of the\r
101 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
102 @param FileName A pointer to the name of the file to find\r
103 within the firmware volume.\r
104 @param FvHandle Upon entry, the pointer to the firmware\r
105 volume to search or NULL if all firmware\r
106 volumes should be searched. Upon exit, the\r
107 actual firmware volume in which the file was\r
108 found.\r
109 @param FileHandle Upon exit, points to the found file's\r
110 handle or NULL if it could not be found.\r
111\r
112 @retval EFI_SUCCESS File was found.\r
113 @retval EFI_NOT_FOUND File was not found.\r
114 @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or\r
5879b875 115 FileName was NULL.\r
116\r
117\r
118**/\r
119typedef\r
120EFI_STATUS\r
8b13229b 121(EFIAPI *EFI_PEI_FV_FIND_FILE_NAME)(\r
dafa11b1 122 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
123 IN CONST EFI_GUID *FileName,\r
44218d2e 124 IN EFI_PEI_FV_HANDLE *FvHandle,\r
dafa11b1 125 OUT EFI_PEI_FILE_HANDLE *FileHandle\r
5879b875 126);\r
127\r
128\r
129/**\r
d7132512
LG
130 Returns information about a specific file.\r
131\r
5879b875 132 This function returns information about a specific\r
00edb218 133 file, including its file name, type, attributes, starting\r
9095d37b
LG
134 address and size.\r
135\r
dafa11b1 136 @param This Points to this instance of the\r
137 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
138 @param FileHandle Handle of the file.\r
139 @param FileInfo Upon exit, points to the file's\r
140 information.\r
5879b875 141\r
00edb218 142 @retval EFI_SUCCESS File information returned.\r
00edb218 143 @retval EFI_INVALID_PARAMETER If FileHandle does not\r
5879b875 144 represent a valid file.\r
dafa11b1 145 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.\r
9095d37b
LG
146\r
147**/\r
5879b875 148typedef\r
dafa11b1 149EFI_STATUS\r
150(EFIAPI *EFI_PEI_FV_GET_FILE_INFO)(\r
9095d37b
LG
151 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
152 IN EFI_PEI_FILE_HANDLE FileHandle,\r
dafa11b1 153 OUT EFI_FV_FILE_INFO *FileInfo\r
5879b875 154);\r
155\r
c7935105
SZ
156/**\r
157 Returns information about a specific file.\r
158\r
159 This function returns information about a specific\r
160 file, including its file name, type, attributes, starting\r
9095d37b 161 address, size and authentication status.\r
c7935105
SZ
162\r
163 @param This Points to this instance of the\r
164 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
165 @param FileHandle Handle of the file.\r
166 @param FileInfo Upon exit, points to the file's\r
167 information.\r
168\r
169 @retval EFI_SUCCESS File information returned.\r
170 @retval EFI_INVALID_PARAMETER If FileHandle does not\r
171 represent a valid file.\r
172 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.\r
173\r
174**/\r
175typedef\r
176EFI_STATUS\r
177(EFIAPI *EFI_PEI_FV_GET_FILE_INFO2)(\r
9095d37b 178 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
c7935105
SZ
179 IN EFI_PEI_FILE_HANDLE FileHandle,\r
180 OUT EFI_FV_FILE_INFO2 *FileInfo\r
181);\r
182\r
5879b875 183/**\r
dafa11b1 184 This function returns information about the firmware volume.\r
9095d37b 185\r
dafa11b1 186 @param This Points to this instance of the\r
187 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
188 @param FvHandle Handle to the firmware handle.\r
189 @param VolumeInfo Points to the returned firmware volume\r
190 information.\r
191\r
192 @retval EFI_SUCCESS Information returned successfully.\r
193 @retval EFI_INVALID_PARAMETER FvHandle does not indicate a valid\r
194 firmware volume or VolumeInfo is NULL.\r
195\r
9095d37b 196**/\r
5879b875 197typedef\r
dafa11b1 198EFI_STATUS\r
199(EFIAPI *EFI_PEI_FV_GET_INFO)(\r
9095d37b
LG
200 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
201 IN EFI_PEI_FV_HANDLE FvHandle,\r
dafa11b1 202 OUT EFI_FV_INFO *VolumeInfo\r
5879b875 203);\r
204\r
205/**\r
d7132512 206 Find the next matching section in the firmware file.\r
9095d37b 207\r
dafa11b1 208 This service enables PEI modules to discover sections\r
209 of a given type within a valid file.\r
9095d37b 210\r
dafa11b1 211 @param This Points to this instance of the\r
212 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
213 @param SearchType A filter to find only sections of this\r
214 type.\r
215 @param FileHandle Handle of firmware file in which to\r
216 search.\r
217 @param SectionData Updated upon return to point to the\r
218 section found.\r
9095d37b 219\r
00edb218 220 @retval EFI_SUCCESS Section was found.\r
00edb218
A
221 @retval EFI_NOT_FOUND Section of the specified type was not\r
222 found. SectionData contains NULL.\r
5879b875 223**/\r
224typedef\r
225EFI_STATUS\r
8b13229b 226(EFIAPI *EFI_PEI_FV_FIND_SECTION)(\r
dafa11b1 227 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
228 IN EFI_SECTION_TYPE SearchType,\r
229 IN EFI_PEI_FILE_HANDLE FileHandle,\r
230 OUT VOID **SectionData\r
5879b875 231);\r
232\r
c7935105
SZ
233/**\r
234 Find the next matching section in the firmware file.\r
235\r
236 This service enables PEI modules to discover sections\r
237 of a given instance and type within a valid file.\r
238\r
239 @param This Points to this instance of the\r
240 EFI_PEI_FIRMWARE_VOLUME_PPI.\r
241 @param SearchType A filter to find only sections of this\r
242 type.\r
243 @param SearchInstance A filter to find the specific instance\r
244 of sections.\r
245 @param FileHandle Handle of firmware file in which to\r
246 search.\r
247 @param SectionData Updated upon return to point to the\r
248 section found.\r
249 @param AuthenticationStatus Updated upon return to point to the\r
250 authentication status for this section.\r
251\r
252 @retval EFI_SUCCESS Section was found.\r
253 @retval EFI_NOT_FOUND Section of the specified type was not\r
254 found. SectionData contains NULL.\r
255**/\r
256typedef\r
257EFI_STATUS\r
258(EFIAPI *EFI_PEI_FV_FIND_SECTION2)(\r
259 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This,\r
260 IN EFI_SECTION_TYPE SearchType,\r
261 IN UINTN SearchInstance,\r
262 IN EFI_PEI_FILE_HANDLE FileHandle,\r
263 OUT VOID **SectionData,\r
264 OUT UINT32 *AuthenticationStatus\r
265);\r
266\r
267#define EFI_PEI_FIRMWARE_VOLUME_PPI_SIGNATURE SIGNATURE_32 ('P', 'F', 'V', 'P')\r
268#define EFI_PEI_FIRMWARE_VOLUME_PPI_REVISION 0x00010030\r
269\r
dafa11b1 270///\r
271/// This PPI provides functions for accessing a memory-mapped firmware volume of a specific format.\r
272///\r
5879b875 273struct _EFI_PEI_FIRMWARE_VOLUME_PPI {\r
00edb218
A
274 EFI_PEI_FV_PROCESS_FV ProcessVolume;\r
275 EFI_PEI_FV_FIND_FILE_TYPE FindFileByType;\r
276 EFI_PEI_FV_FIND_FILE_NAME FindFileByName;\r
277 EFI_PEI_FV_GET_FILE_INFO GetFileInfo;\r
278 EFI_PEI_FV_GET_INFO GetVolumeInfo;\r
279 EFI_PEI_FV_FIND_SECTION FindSectionByType;\r
c7935105
SZ
280 EFI_PEI_FV_GET_FILE_INFO2 GetFileInfo2;\r
281 EFI_PEI_FV_FIND_SECTION2 FindSectionByType2;\r
282 ///\r
283 /// Signature is used to keep backward-compatibility, set to {'P','F','V','P'}.\r
284 ///\r
285 UINT32 Signature;\r
286 ///\r
287 /// Revision for further extension.\r
288 ///\r
289 UINT32 Revision;\r
dafa11b1 290};\r
5879b875 291\r
00edb218 292extern EFI_GUID gEfiPeiFirmwareVolumePpiGuid;\r
5879b875 293\r
9095d37b 294#endif\r