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