2 The internal header file for firmware volume related definitions.
4 Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
20 #define GET_OCCUPIED_SIZE(ActualSize, Alignment) \
21 ((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1)))
24 #define PEI_FW_VOL_SIGNATURE SIGNATURE_32('P','F','W','V')
29 EFI_PEI_FIRMWARE_VOLUME_PPI Fv
;
30 } PEI_FW_VOL_INSTANCE
;
32 #define PEI_FW_VOL_INSTANCE_FROM_FV_THIS(a) \
33 CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE)
37 Process a firmware volume and create a volume handle.
39 Create a volume handle from the information in the buffer. For
40 memory-mapped firmware volumes, Buffer and BufferSize refer to
41 the start of the firmware volume and the firmware volume size.
42 For non memory-mapped firmware volumes, this points to a
43 buffer which contains the necessary information for creating
44 the firmware volume handle. Normally, these values are derived
45 from the EFI_FIRMWARE_VOLUME_INFO_PPI.
48 @param This Points to this instance of the
49 EFI_PEI_FIRMWARE_VOLUME_PPI.
50 @param Buffer Points to the start of the buffer.
51 @param BufferSize Size of the buffer.
52 @param FvHandle Points to the returned firmware volume
53 handle. The firmware volume handle must
54 be unique within the system.
56 @retval EFI_SUCCESS Firmware volume handle created.
57 @retval EFI_VOLUME_CORRUPTED Volume was corrupt.
62 PeiFfsFvPpiProcessVolume (
63 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
66 OUT EFI_PEI_FV_HANDLE
*FvHandle
70 Finds the next file of the specified type.
72 This service enables PEI modules to discover additional firmware files.
73 The FileHandle must be unique within the system.
75 @param This Points to this instance of the
76 EFI_PEI_FIRMWARE_VOLUME_PPI.
77 @param SearchType A filter to find only files of this type. Type
78 EFI_FV_FILETYPE_ALL causes no filtering to be
80 @param FvHandle Handle of firmware volume in which to
82 @param FileHandle Points to the current handle from which to
83 begin searching or NULL to start at the
84 beginning of the firmware volume. Updated
85 upon return to reflect the file found.
87 @retval EFI_SUCCESS The file was found.
88 @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.
93 PeiFfsFvPpiFindFileByType (
94 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
95 IN EFI_FV_FILETYPE SearchType
,
96 IN EFI_PEI_FV_HANDLE FvHandle
,
97 IN OUT EFI_PEI_FILE_HANDLE
*FileHandle
101 Find a file within a volume by its name.
103 This service searches for files with a specific name, within
104 either the specified firmware volume or all firmware volumes.
106 @param This Points to this instance of the
107 EFI_PEI_FIRMWARE_VOLUME_PPI.
108 @param FileName A pointer to the name of the file to find
109 within the firmware volume.
110 @param FvHandle Upon entry, the pointer to the firmware
111 volume to search or NULL if all firmware
112 volumes should be searched. Upon exit, the
113 actual firmware volume in which the file was
115 @param FileHandle Upon exit, points to the found file's
116 handle or NULL if it could not be found.
118 @retval EFI_SUCCESS File was found.
119 @retval EFI_NOT_FOUND File was not found.
120 @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or
127 PeiFfsFvPpiFindFileByName (
128 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
129 IN CONST EFI_GUID
*FileName
,
130 IN EFI_PEI_FV_HANDLE
*FvHandle
,
131 OUT EFI_PEI_FILE_HANDLE
*FileHandle
135 Find the next matching section in the firmware file.
137 This service enables PEI modules to discover sections
138 of a given type within a valid file.
140 @param This Points to this instance of the
141 EFI_PEI_FIRMWARE_VOLUME_PPI.
142 @param SearchType A filter to find only sections of this
144 @param FileHandle Handle of firmware file in which to
146 @param SectionData Updated upon return to point to the
149 @retval EFI_SUCCESS Section was found.
150 @retval EFI_NOT_FOUND Section of the specified type was not
151 found. SectionData contains NULL.
155 PeiFfsFvPpiFindSectionByType (
156 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
157 IN EFI_SECTION_TYPE SearchType
,
158 IN EFI_PEI_FILE_HANDLE FileHandle
,
159 OUT VOID
**SectionData
163 Find the next matching section in the firmware file.
165 This service enables PEI modules to discover sections
166 of a given instance and type within a valid file.
168 @param This Points to this instance of the
169 EFI_PEI_FIRMWARE_VOLUME_PPI.
170 @param SearchType A filter to find only sections of this
172 @param SearchInstance A filter to find the specific instance
174 @param FileHandle Handle of firmware file in which to
176 @param SectionData Updated upon return to point to the
178 @param AuthenticationStatus Updated upon return to point to the
179 authentication status for this section.
181 @retval EFI_SUCCESS Section was found.
182 @retval EFI_NOT_FOUND Section of the specified type was not
183 found. SectionData contains NULL.
187 PeiFfsFvPpiFindSectionByType2 (
188 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
189 IN EFI_SECTION_TYPE SearchType
,
190 IN UINTN SearchInstance
,
191 IN EFI_PEI_FILE_HANDLE FileHandle
,
192 OUT VOID
**SectionData
,
193 OUT UINT32
*AuthenticationStatus
197 Returns information about a specific file.
199 This function returns information about a specific
200 file, including its file name, type, attributes, starting
203 @param This Points to this instance of the
204 EFI_PEI_FIRMWARE_VOLUME_PPI.
205 @param FileHandle Handle of the file.
206 @param FileInfo Upon exit, points to the file's
209 @retval EFI_SUCCESS File information returned.
210 @retval EFI_INVALID_PARAMETER If FileHandle does not
211 represent a valid file.
212 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.
217 PeiFfsFvPpiGetFileInfo (
218 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
219 IN EFI_PEI_FILE_HANDLE FileHandle
,
220 OUT EFI_FV_FILE_INFO
*FileInfo
224 Returns information about a specific file.
226 This function returns information about a specific
227 file, including its file name, type, attributes, starting
228 address, size and authentication status.
230 @param This Points to this instance of the
231 EFI_PEI_FIRMWARE_VOLUME_PPI.
232 @param FileHandle Handle of the file.
233 @param FileInfo Upon exit, points to the file's
236 @retval EFI_SUCCESS File information returned.
237 @retval EFI_INVALID_PARAMETER If FileHandle does not
238 represent a valid file.
239 @retval EFI_INVALID_PARAMETER If FileInfo is NULL.
244 PeiFfsFvPpiGetFileInfo2 (
245 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
246 IN EFI_PEI_FILE_HANDLE FileHandle
,
247 OUT EFI_FV_FILE_INFO2
*FileInfo
251 This function returns information about the firmware volume.
253 @param This Points to this instance of the
254 EFI_PEI_FIRMWARE_VOLUME_PPI.
255 @param FvHandle Handle to the firmware handle.
256 @param VolumeInfo Points to the returned firmware volume
259 @retval EFI_SUCCESS Information returned successfully.
260 @retval EFI_INVALID_PARAMETER FvHandle does not indicate a valid
261 firmware volume or VolumeInfo is NULL.
266 PeiFfsFvPpiGetVolumeInfo (
267 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI
*This
,
268 IN EFI_PEI_FV_HANDLE FvHandle
,
269 OUT EFI_FV_INFO
*VolumeInfo
273 Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE.
275 @param FvHandle The handle of a FV.
277 @retval NULL if can not find.
278 @return Pointer of corresponding PEI_CORE_FV_HANDLE.
281 FvHandleToCoreHandle (
282 IN EFI_PEI_FV_HANDLE FvHandle
286 Given the input file pointer, search for the next matching file in the
287 FFS volume as defined by SearchType. The search starts from FileHeader inside
288 the Firmware Volume defined by FwVolHeader.
291 @param FvHandle Pointer to the FV header of the volume to search
292 @param FileName File name
293 @param SearchType Filter to find only files of this type.
294 Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
295 @param FileHandle This parameter must point to a valid FFS volume.
296 @param AprioriFile Pointer to AprioriFile image in this FV if has
298 @return EFI_NOT_FOUND No files matching the search criteria were found
299 @retval EFI_SUCCESS Success to search given file
304 IN CONST EFI_PEI_FV_HANDLE FvHandle
,
305 IN CONST EFI_GUID
*FileName
, OPTIONAL
306 IN EFI_FV_FILETYPE SearchType
,
307 IN OUT EFI_PEI_FILE_HANDLE
*FileHandle
,
308 IN OUT EFI_PEI_FV_HANDLE
*AprioriFile OPTIONAL
312 Report the information for a new discoveried FV in unknown format.
314 If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for specifical FV format, but
315 the FV in this FV format has been discoveried, then the information of this FV
316 will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array.
317 Also a notification would be installed for unknown FV format guid, if EFI_PEI_FIRMWARE_VOLUME_PPI
318 is installed later by platform's PEIM, the original unknown FV will be processed by
319 using new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
321 @param PrivateData Point to instance of PEI_CORE_INSTANCE
322 @param FvInfo2Ppi Point to FvInfo2 PPI.
324 @retval EFI_OUT_OF_RESOURCES The FV info array in PEI_CORE_INSTANCE has no more spaces.
325 @retval EFI_SUCCESS Success to add the information for unknown FV.
328 AddUnknownFormatFvInfo (
329 IN PEI_CORE_INSTANCE
*PrivateData
,
330 IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI
*FvInfo2Ppi
334 Find the FV information according to FV format guid.
336 This routine also will remove the FV information found by given FV format guid from
337 PrivateData->UnknownFvInfo[].
339 @param PrivateData Point to instance of PEI_CORE_INSTANCE
340 @param Format Point to given FV format guid
341 @param FvInfo On return, the pointer of FV information buffer in given FV format guid
342 @param FvInfoSize On return, the size of FV information buffer.
343 @param AuthenticationStatus On return, the authentication status of FV information buffer.
345 @retval EFI_NOT_FOUND The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI
346 @retval EFI_SUCCESS Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
349 FindUnknownFormatFvInfo (
350 IN PEI_CORE_INSTANCE
*PrivateData
,
353 OUT UINT32
*FvInfoSize
,
354 OUT UINT32
*AuthenticationStatus
358 Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI.
360 When a EFI_PEI_FIRMWARE_VOLUME_PPI is installed to support new FV format, this
361 routine is called to process all discoveried FVs in this format.
363 @param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation
364 @param NotifyDescriptor Address of the notification descriptor data structure.
365 @param Ppi Address of the PPI that was installed.
367 @retval EFI_SUCCESS The notification callback is processed correctly.
371 ThirdPartyFvPpiNotifyCallback (
372 IN EFI_PEI_SERVICES
**PeiServices
,
373 IN EFI_PEI_NOTIFY_DESCRIPTOR
*NotifyDescriptor
,