1 /** @file 2 The internal header file for firmware volume related definitions. 3 4 Copyright (c) 2009 - 2018, Intel Corporation. All rights reserved.<BR> 5 SPDX-License-Identifier: BSD-2-Clause-Patent 6 7 **/ 8 9 #ifndef _FWVOL_H_ 10 #define _FWVOL_H_ 11 12 #include "PeiMain.h" 13 14 #define GET_OCCUPIED_SIZE(ActualSize, Alignment) \ 15 ((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1))) 16 17 18 #define PEI_FW_VOL_SIGNATURE SIGNATURE_32('P','F','W','V') 19 20 typedef struct { 21 UINTN Signature; 22 BOOLEAN IsFfs3Fv; 23 EFI_PEI_FIRMWARE_VOLUME_PPI Fv; 24 } PEI_FW_VOL_INSTANCE; 25 26 #define PEI_FW_VOL_INSTANCE_FROM_FV_THIS(a) \ 27 CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE) 28 29 30 /** 31 Process a firmware volume and create a volume handle. 32 33 Create a volume handle from the information in the buffer. For 34 memory-mapped firmware volumes, Buffer and BufferSize refer to 35 the start of the firmware volume and the firmware volume size. 36 For non memory-mapped firmware volumes, this points to a 37 buffer which contains the necessary information for creating 38 the firmware volume handle. Normally, these values are derived 39 from the EFI_FIRMWARE_VOLUME_INFO_PPI. 40 41 42 @param This Points to this instance of the 43 EFI_PEI_FIRMWARE_VOLUME_PPI. 44 @param Buffer Points to the start of the buffer. 45 @param BufferSize Size of the buffer. 46 @param FvHandle Points to the returned firmware volume 47 handle. The firmware volume handle must 48 be unique within the system. 49 50 @retval EFI_SUCCESS Firmware volume handle created. 51 @retval EFI_VOLUME_CORRUPTED Volume was corrupt. 52 53 **/ 54 EFI_STATUS 55 EFIAPI 56 PeiFfsFvPpiProcessVolume ( 57 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 58 IN VOID *Buffer, 59 IN UINTN BufferSize, 60 OUT EFI_PEI_FV_HANDLE *FvHandle 61 ); 62 63 /** 64 Finds the next file of the specified type. 65 66 This service enables PEI modules to discover additional firmware files. 67 The FileHandle must be unique within the system. 68 69 @param This Points to this instance of the 70 EFI_PEI_FIRMWARE_VOLUME_PPI. 71 @param SearchType A filter to find only files of this type. Type 72 EFI_FV_FILETYPE_ALL causes no filtering to be 73 done. 74 @param FvHandle Handle of firmware volume in which to 75 search. 76 @param FileHandle Points to the current handle from which to 77 begin searching or NULL to start at the 78 beginning of the firmware volume. Updated 79 upon return to reflect the file found. 80 81 @retval EFI_SUCCESS The file was found. 82 @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL. 83 84 **/ 85 EFI_STATUS 86 EFIAPI 87 PeiFfsFvPpiFindFileByType ( 88 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 89 IN EFI_FV_FILETYPE SearchType, 90 IN EFI_PEI_FV_HANDLE FvHandle, 91 IN OUT EFI_PEI_FILE_HANDLE *FileHandle 92 ); 93 94 /** 95 Find a file within a volume by its name. 96 97 This service searches for files with a specific name, within 98 either the specified firmware volume or all firmware volumes. 99 100 @param This Points to this instance of the 101 EFI_PEI_FIRMWARE_VOLUME_PPI. 102 @param FileName A pointer to the name of the file to find 103 within the firmware volume. 104 @param FvHandle Upon entry, the pointer to the firmware 105 volume to search or NULL if all firmware 106 volumes should be searched. Upon exit, the 107 actual firmware volume in which the file was 108 found. 109 @param FileHandle Upon exit, points to the found file's 110 handle or NULL if it could not be found. 111 112 @retval EFI_SUCCESS File was found. 113 @retval EFI_NOT_FOUND File was not found. 114 @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or 115 FileName was NULL. 116 117 118 **/ 119 EFI_STATUS 120 EFIAPI 121 PeiFfsFvPpiFindFileByName ( 122 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 123 IN CONST EFI_GUID *FileName, 124 IN EFI_PEI_FV_HANDLE *FvHandle, 125 OUT EFI_PEI_FILE_HANDLE *FileHandle 126 ); 127 128 /** 129 Find the next matching section in the firmware file. 130 131 This service enables PEI modules to discover sections 132 of a given type within a valid file. 133 134 @param This Points to this instance of the 135 EFI_PEI_FIRMWARE_VOLUME_PPI. 136 @param SearchType A filter to find only sections of this 137 type. 138 @param FileHandle Handle of firmware file in which to 139 search. 140 @param SectionData Updated upon return to point to the 141 section found. 142 143 @retval EFI_SUCCESS Section was found. 144 @retval EFI_NOT_FOUND Section of the specified type was not 145 found. SectionData contains NULL. 146 **/ 147 EFI_STATUS 148 EFIAPI 149 PeiFfsFvPpiFindSectionByType ( 150 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 151 IN EFI_SECTION_TYPE SearchType, 152 IN EFI_PEI_FILE_HANDLE FileHandle, 153 OUT VOID **SectionData 154 ); 155 156 /** 157 Find the next matching section in the firmware file. 158 159 This service enables PEI modules to discover sections 160 of a given instance and type within a valid file. 161 162 @param This Points to this instance of the 163 EFI_PEI_FIRMWARE_VOLUME_PPI. 164 @param SearchType A filter to find only sections of this 165 type. 166 @param SearchInstance A filter to find the specific instance 167 of sections. 168 @param FileHandle Handle of firmware file in which to 169 search. 170 @param SectionData Updated upon return to point to the 171 section found. 172 @param AuthenticationStatus Updated upon return to point to the 173 authentication status for this section. 174 175 @retval EFI_SUCCESS Section was found. 176 @retval EFI_NOT_FOUND Section of the specified type was not 177 found. SectionData contains NULL. 178 **/ 179 EFI_STATUS 180 EFIAPI 181 PeiFfsFvPpiFindSectionByType2 ( 182 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 183 IN EFI_SECTION_TYPE SearchType, 184 IN UINTN SearchInstance, 185 IN EFI_PEI_FILE_HANDLE FileHandle, 186 OUT VOID **SectionData, 187 OUT UINT32 *AuthenticationStatus 188 ); 189 190 /** 191 Returns information about a specific file. 192 193 This function returns information about a specific 194 file, including its file name, type, attributes, starting 195 address and size. 196 197 @param This Points to this instance of the 198 EFI_PEI_FIRMWARE_VOLUME_PPI. 199 @param FileHandle Handle of the file. 200 @param FileInfo Upon exit, points to the file's 201 information. 202 203 @retval EFI_SUCCESS File information returned. 204 @retval EFI_INVALID_PARAMETER If FileHandle does not 205 represent a valid file. 206 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 207 208 **/ 209 EFI_STATUS 210 EFIAPI 211 PeiFfsFvPpiGetFileInfo ( 212 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 213 IN EFI_PEI_FILE_HANDLE FileHandle, 214 OUT EFI_FV_FILE_INFO *FileInfo 215 ); 216 217 /** 218 Returns information about a specific file. 219 220 This function returns information about a specific 221 file, including its file name, type, attributes, starting 222 address, size and authentication status. 223 224 @param This Points to this instance of the 225 EFI_PEI_FIRMWARE_VOLUME_PPI. 226 @param FileHandle Handle of the file. 227 @param FileInfo Upon exit, points to the file's 228 information. 229 230 @retval EFI_SUCCESS File information returned. 231 @retval EFI_INVALID_PARAMETER If FileHandle does not 232 represent a valid file. 233 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 234 235 **/ 236 EFI_STATUS 237 EFIAPI 238 PeiFfsFvPpiGetFileInfo2 ( 239 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 240 IN EFI_PEI_FILE_HANDLE FileHandle, 241 OUT EFI_FV_FILE_INFO2 *FileInfo 242 ); 243 244 /** 245 This function returns information about the firmware volume. 246 247 @param This Points to this instance of the 248 EFI_PEI_FIRMWARE_VOLUME_PPI. 249 @param FvHandle Handle to the firmware handle. 250 @param VolumeInfo Points to the returned firmware volume 251 information. 252 253 @retval EFI_SUCCESS Information returned successfully. 254 @retval EFI_INVALID_PARAMETER FvHandle does not indicate a valid 255 firmware volume or VolumeInfo is NULL. 256 257 **/ 258 EFI_STATUS 259 EFIAPI 260 PeiFfsFvPpiGetVolumeInfo ( 261 IN CONST EFI_PEI_FIRMWARE_VOLUME_PPI *This, 262 IN EFI_PEI_FV_HANDLE FvHandle, 263 OUT EFI_FV_INFO *VolumeInfo 264 ); 265 266 /** 267 Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE. 268 269 @param FvHandle The handle of a FV. 270 271 @retval NULL if can not find. 272 @return Pointer of corresponding PEI_CORE_FV_HANDLE. 273 **/ 274 PEI_CORE_FV_HANDLE * 275 FvHandleToCoreHandle ( 276 IN EFI_PEI_FV_HANDLE FvHandle 277 ); 278 279 /** 280 Given the input file pointer, search for the next matching file in the 281 FFS volume as defined by SearchType. The search starts from FileHeader inside 282 the Firmware Volume defined by FwVolHeader. 283 284 285 @param FvHandle Pointer to the FV header of the volume to search 286 @param FileName File name 287 @param SearchType Filter to find only files of this type. 288 Type EFI_FV_FILETYPE_ALL causes no filtering to be done. 289 @param FileHandle This parameter must point to a valid FFS volume. 290 @param AprioriFile Pointer to AprioriFile image in this FV if has 291 292 @return EFI_NOT_FOUND No files matching the search criteria were found 293 @retval EFI_SUCCESS Success to search given file 294 295 **/ 296 EFI_STATUS 297 FindFileEx ( 298 IN CONST EFI_PEI_FV_HANDLE FvHandle, 299 IN CONST EFI_GUID *FileName, OPTIONAL 300 IN EFI_FV_FILETYPE SearchType, 301 IN OUT EFI_PEI_FILE_HANDLE *FileHandle, 302 IN OUT EFI_PEI_FV_HANDLE *AprioriFile OPTIONAL 303 ); 304 305 /** 306 Report the information for a new discoveried FV in unknown format. 307 308 If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for specifical FV format, but 309 the FV in this FV format has been discoveried, then the information of this FV 310 will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array. 311 Also a notification would be installed for unknown FV format guid, if EFI_PEI_FIRMWARE_VOLUME_PPI 312 is installed later by platform's PEIM, the original unknown FV will be processed by 313 using new installed EFI_PEI_FIRMWARE_VOLUME_PPI. 314 315 @param PrivateData Point to instance of PEI_CORE_INSTANCE 316 @param FvInfo2Ppi Point to FvInfo2 PPI. 317 318 @retval EFI_OUT_OF_RESOURCES The FV info array in PEI_CORE_INSTANCE has no more spaces. 319 @retval EFI_SUCCESS Success to add the information for unknown FV. 320 **/ 321 EFI_STATUS 322 AddUnknownFormatFvInfo ( 323 IN PEI_CORE_INSTANCE *PrivateData, 324 IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI *FvInfo2Ppi 325 ); 326 327 /** 328 Find the FV information according to FV format guid. 329 330 This routine also will remove the FV information found by given FV format guid from 331 PrivateData->UnknownFvInfo[]. 332 333 @param PrivateData Point to instance of PEI_CORE_INSTANCE 334 @param Format Point to given FV format guid 335 @param FvInfo On return, the pointer of FV information buffer in given FV format guid 336 @param FvInfoSize On return, the size of FV information buffer. 337 @param AuthenticationStatus On return, the authentication status of FV information buffer. 338 339 @retval EFI_NOT_FOUND The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI 340 @retval EFI_SUCCESS Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI. 341 **/ 342 EFI_STATUS 343 FindUnknownFormatFvInfo ( 344 IN PEI_CORE_INSTANCE *PrivateData, 345 IN EFI_GUID *Format, 346 OUT VOID **FvInfo, 347 OUT UINT32 *FvInfoSize, 348 OUT UINT32 *AuthenticationStatus 349 ); 350 351 /** 352 Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI. 353 354 When a EFI_PEI_FIRMWARE_VOLUME_PPI is installed to support new FV format, this 355 routine is called to process all discoveried FVs in this format. 356 357 @param PeiServices An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation 358 @param NotifyDescriptor Address of the notification descriptor data structure. 359 @param Ppi Address of the PPI that was installed. 360 361 @retval EFI_SUCCESS The notification callback is processed correctly. 362 **/ 363 EFI_STATUS 364 EFIAPI 365 ThirdPartyFvPpiNotifyCallback ( 366 IN EFI_PEI_SERVICES **PeiServices, 367 IN EFI_PEI_NOTIFY_DESCRIPTOR *NotifyDescriptor, 368 IN VOID *Ppi 369 ); 370 371 #endif 372