1 /** @file 2 The internal header file for firmware volume related definitions. 3 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 9 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. 12 13 **/ 14 15 #ifndef _FWVOL_H_ 16 #define _FWVOL_H_ 17 18 #include "PeiMain.h" 19 20 #define GET_OCCUPIED_SIZE(ActualSize, Alignment) \ 21 ((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1))) 22 23 24 #define PEI_FW_VOL_SIGNATURE SIGNATURE_32('P','F','W','V') 25 26 typedef struct { 27 UINTN Signature; 28 BOOLEAN IsFfs3Fv; 29 EFI_PEI_FIRMWARE_VOLUME_PPI Fv; 30 } PEI_FW_VOL_INSTANCE; 31 32 #define PEI_FW_VOL_INSTANCE_FROM_FV_THIS(a) \ 33 CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE) 34 35 36 /** 37 Process a firmware volume and create a volume handle. 38 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. 46 47 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. 55 56 @retval EFI_SUCCESS Firmware volume handle created. 57 @retval EFI_VOLUME_CORRUPTED Volume was corrupt. 58 59 **/ 60 EFI_STATUS 61 EFIAPI 62 PeiFfsFvPpiProcessVolume ( 63 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 64 IN VOID *Buffer, 65 IN UINTN BufferSize, 66 OUT EFI_PEI_FV_HANDLE *FvHandle 67 ); 68 69 /** 70 Finds the next file of the specified type. 71 72 This service enables PEI modules to discover additional firmware files. 73 The FileHandle must be unique within the system. 74 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 79 done. 80 @param FvHandle Handle of firmware volume in which to 81 search. 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. 86 87 @retval EFI_SUCCESS The file was found. 88 @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL. 89 90 **/ 91 EFI_STATUS 92 EFIAPI 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 98 ); 99 100 /** 101 Find a file within a volume by its name. 102 103 This service searches for files with a specific name, within 104 either the specified firmware volume or all firmware volumes. 105 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 114 found. 115 @param FileHandle Upon exit, points to the found file's 116 handle or NULL if it could not be found. 117 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 121 FileName was NULL. 122 123 124 **/ 125 EFI_STATUS 126 EFIAPI 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 132 ); 133 134 /** 135 Find the next matching section in the firmware file. 136 137 This service enables PEI modules to discover sections 138 of a given type within a valid file. 139 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 143 type. 144 @param FileHandle Handle of firmware file in which to 145 search. 146 @param SectionData Updated upon return to point to the 147 section found. 148 149 @retval EFI_SUCCESS Section was found. 150 @retval EFI_NOT_FOUND Section of the specified type was not 151 found. SectionData contains NULL. 152 **/ 153 EFI_STATUS 154 EFIAPI 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 160 ); 161 162 /** 163 Find the next matching section in the firmware file. 164 165 This service enables PEI modules to discover sections 166 of a given instance and type within a valid file. 167 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 171 type. 172 @param SearchInstance A filter to find the specific instance 173 of sections. 174 @param FileHandle Handle of firmware file in which to 175 search. 176 @param SectionData Updated upon return to point to the 177 section found. 178 @param AuthenticationStatus Updated upon return to point to the 179 authentication status for this section. 180 181 @retval EFI_SUCCESS Section was found. 182 @retval EFI_NOT_FOUND Section of the specified type was not 183 found. SectionData contains NULL. 184 **/ 185 EFI_STATUS 186 EFIAPI 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 194 ); 195 196 /** 197 Returns information about a specific file. 198 199 This function returns information about a specific 200 file, including its file name, type, attributes, starting 201 address and size. 202 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 207 information. 208 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. 213 214 **/ 215 EFI_STATUS 216 EFIAPI 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 221 ); 222 223 /** 224 Returns information about a specific file. 225 226 This function returns information about a specific 227 file, including its file name, type, attributes, starting 228 address, size and authentication status. 229 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 234 information. 235 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. 240 241 **/ 242 EFI_STATUS 243 EFIAPI 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 248 ); 249 250 /** 251 This function returns information about the firmware volume. 252 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 257 information. 258 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. 262 263 **/ 264 EFI_STATUS 265 EFIAPI 266 PeiFfsFvPpiGetVolumeInfo ( 267 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 268 IN EFI_PEI_FV_HANDLE FvHandle, 269 OUT EFI_FV_INFO *VolumeInfo 270 ); 271 272 /** 273 Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE. 274 275 @param FvHandle The handle of a FV. 276 277 @retval NULL if can not find. 278 @return Pointer of corresponding PEI_CORE_FV_HANDLE. 279 **/ 280 PEI_CORE_FV_HANDLE * 281 FvHandleToCoreHandle ( 282 IN EFI_PEI_FV_HANDLE FvHandle 283 ); 284 285 /** 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. 289 290 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 297 298 @return EFI_NOT_FOUND No files matching the search criteria were found 299 @retval EFI_SUCCESS Success to search given file 300 301 **/ 302 EFI_STATUS 303 FindFileEx ( 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 309 ); 310 311 /** 312 Report the information for a new discoveried FV in unknown format. 313 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. 320 321 @param PrivateData Point to instance of PEI_CORE_INSTANCE 322 @param FvInfo2Ppi Point to FvInfo2 PPI. 323 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. 326 **/ 327 EFI_STATUS 328 AddUnknownFormatFvInfo ( 329 IN PEI_CORE_INSTANCE *PrivateData, 330 IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI *FvInfo2Ppi 331 ); 332 333 /** 334 Find the FV information according to FV format guid. 335 336 This routine also will remove the FV information found by given FV format guid from 337 PrivateData->UnknownFvInfo[]. 338 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. 344 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. 347 **/ 348 EFI_STATUS 349 FindUnknownFormatFvInfo ( 350 IN PEI_CORE_INSTANCE *PrivateData, 351 IN EFI_GUID *Format, 352 OUT VOID **FvInfo, 353 OUT UINT32 *FvInfoSize, 354 OUT UINT32 *AuthenticationStatus 355 ); 356 357 /** 358 Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI. 359 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. 362 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. 366 367 @retval EFI_SUCCESS The notification callback is processed correctly. 368 **/ 369 EFI_STATUS 370 EFIAPI 371 ThirdPartyFvPpiNotifyCallback ( 372 IN EFI_PEI_SERVICES **PeiServices, 373 IN EFI_PEI_NOTIFY_DESCRIPTOR *NotifyDescriptor, 374 IN VOID *Ppi 375 ); 376 377 #endif 378