1 /** @file 2 MDE DXE Services Library provides functions that simplify the development of DXE Drivers. 3 These functions help access data from sections of FFS files or from file path. 4 5 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR> 6 (C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR> 7 SPDX-License-Identifier: BSD-2-Clause-Patent 8 9 **/ 10 11 #ifndef __DXE_SERVICES_LIB_H__ 12 #define __DXE_SERVICES_LIB_H__ 13 14 /** 15 Searches all the available firmware volumes and returns the first matching FFS section. 16 17 This function searches all the firmware volumes for FFS files with FV file type specified by FileType 18 The order that the firmware volumes is searched is not deterministic. For each available FV a search 19 is made for FFS file of type FileType. If the FV contains more than one FFS file with the same FileType, 20 the FileInstance instance will be the matched FFS file. For each FFS file found a search 21 is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances 22 of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. 23 Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. 24 It is the caller's responsibility to use FreePool() to free the allocated buffer. 25 See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections 26 are retrieved from an FFS file based on SectionType and SectionInstance. 27 28 If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, 29 the search will be retried with a section type of EFI_SECTION_PE32. 30 This function must be called with a TPL <= TPL_NOTIFY. 31 32 If Buffer is NULL, then ASSERT(). 33 If Size is NULL, then ASSERT(). 34 35 @param FileType Indicates the FV file type to search for within all available FVs. 36 @param FileInstance Indicates which file instance within all available FVs specified by FileType. 37 FileInstance starts from zero. 38 @param SectionType Indicates the FFS section type to search for within the FFS file 39 specified by FileType with FileInstance. 40 @param SectionInstance Indicates which section instance within the FFS file 41 specified by FileType with FileInstance to retrieve. SectionInstance starts from zero. 42 @param Buffer On output, a pointer to a callee allocated buffer containing the FFS file section that was found. 43 Is it the caller's responsibility to free this buffer using FreePool(). 44 @param Size On output, a pointer to the size, in bytes, of Buffer. 45 46 @retval EFI_SUCCESS The specified FFS section was returned. 47 @retval EFI_NOT_FOUND The specified FFS section could not be found. 48 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve the matching FFS section. 49 @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a device error. 50 @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the firmware volume that 51 contains the matching FFS section does not allow reads. 52 **/ 53 EFI_STATUS 54 EFIAPI 55 GetSectionFromAnyFvByFileType ( 56 IN EFI_FV_FILETYPE FileType, 57 IN UINTN FileInstance, 58 IN EFI_SECTION_TYPE SectionType, 59 IN UINTN SectionInstance, 60 OUT VOID **Buffer, 61 OUT UINTN *Size 62 ); 63 64 /** 65 Searches all the available firmware volumes and returns the first matching FFS section. 66 67 This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid. 68 The order in which the firmware volumes are searched is not deterministic. For each FFS file found, a search 69 is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance instances 70 of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. 71 Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. 72 It is the caller's responsibility to use FreePool() to free the allocated buffer. 73 See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections 74 are retrieved from an FFS file based on SectionType and SectionInstance. 75 76 If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, 77 the search will be retried with a section type of EFI_SECTION_PE32. 78 This function must be called with a TPL <= TPL_NOTIFY. 79 80 If NameGuid is NULL, then ASSERT(). 81 If Buffer is NULL, then ASSERT(). 82 If Size is NULL, then ASSERT(). 83 84 85 @param NameGuid A pointer to to the FFS filename GUID to search for 86 within any of the firmware volumes in the platform. 87 @param SectionType Indicates the FFS section type to search for within 88 the FFS file specified by NameGuid. 89 @param SectionInstance Indicates which section instance within the FFS file 90 specified by NameGuid to retrieve. 91 @param Buffer On output, a pointer to a callee-allocated buffer 92 containing the FFS file section that was found. 93 It is the caller's responsibility to free this 94 buffer using FreePool(). 95 @param Size On output, a pointer to the size, in bytes, of Buffer. 96 97 @retval EFI_SUCCESS The specified FFS section was returned. 98 @retval EFI_NOT_FOUND The specified FFS section could not be found. 99 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve 100 the matching FFS section. 101 @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a 102 device error. 103 @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the 104 firmware volume that contains the matching FFS 105 section does not allow reads. 106 **/ 107 EFI_STATUS 108 EFIAPI 109 GetSectionFromAnyFv ( 110 IN CONST EFI_GUID *NameGuid, 111 IN EFI_SECTION_TYPE SectionType, 112 IN UINTN SectionInstance, 113 OUT VOID **Buffer, 114 OUT UINTN *Size 115 ); 116 117 /** 118 Searches the firmware volume that the currently executing module was loaded from and returns the first matching FFS section. 119 120 This function searches the firmware volume that the currently executing module was loaded 121 from for an FFS file with an FFS filename specified by NameGuid. If the FFS file is found, a search 122 is made for FFS sections of type SectionType. If the FFS file contains at least SectionInstance 123 instances of the FFS section specified by SectionType, then the SectionInstance instance is returned in Buffer. 124 Buffer is allocated using AllocatePool(), and the size of the allocated buffer is returned in Size. 125 It is the caller's responsibility to use FreePool() to free the allocated buffer. 126 See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for details on how sections are retrieved from 127 an FFS file based on SectionType and SectionInstance. 128 129 If the currently executing module was not loaded from a firmware volume, then EFI_NOT_FOUND is returned. 130 If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, 131 the search will be retried with a section type of EFI_SECTION_PE32. 132 133 This function must be called with a TPL <= TPL_NOTIFY. 134 If NameGuid is NULL, then ASSERT(). 135 If Buffer is NULL, then ASSERT(). 136 If Size is NULL, then ASSERT(). 137 138 @param NameGuid A pointer to to the FFS filename GUID to search for 139 within the firmware volumes that the currently 140 executing module was loaded from. 141 @param SectionType Indicates the FFS section type to search for within 142 the FFS file specified by NameGuid. 143 @param SectionInstance Indicates which section instance within the FFS 144 file specified by NameGuid to retrieve. 145 @param Buffer On output, a pointer to a callee allocated buffer 146 containing the FFS file section that was found. 147 It is the caller's responsibility to free this buffer 148 using FreePool(). 149 @param Size On output, a pointer to the size, in bytes, of Buffer. 150 151 152 @retval EFI_SUCCESS The specified FFS section was returned. 153 @retval EFI_NOT_FOUND The specified FFS section could not be found. 154 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve 155 the matching FFS section. 156 @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a 157 device error. 158 @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the 159 firmware volume that contains the matching FFS 160 section does not allow reads. 161 **/ 162 EFI_STATUS 163 EFIAPI 164 GetSectionFromFv ( 165 IN CONST EFI_GUID *NameGuid, 166 IN EFI_SECTION_TYPE SectionType, 167 IN UINTN SectionInstance, 168 OUT VOID **Buffer, 169 OUT UINTN *Size 170 ); 171 172 173 /** 174 Searches the FFS file the currently executing module was loaded from and returns the first matching FFS section. 175 176 This function searches the FFS file that the currently executing module was loaded from for a FFS sections of type SectionType. 177 If the FFS file contains at least SectionInstance instances of the FFS section specified by SectionType, 178 then the SectionInstance instance is returned in Buffer. Buffer is allocated using AllocatePool(), 179 and the size of the allocated buffer is returned in Size. It is the caller's responsibility 180 to use FreePool() to free the allocated buffer. See EFI_FIRMWARE_VOLUME2_PROTOCOL.ReadSection() for 181 details on how sections are retrieved from an FFS file based on SectionType and SectionInstance. 182 183 If the currently executing module was not loaded from an FFS file, then EFI_NOT_FOUND is returned. 184 If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, 185 the search will be retried with a section type of EFI_SECTION_PE32. 186 This function must be called with a TPL <= TPL_NOTIFY. 187 188 If Buffer is NULL, then ASSERT(). 189 If Size is NULL, then ASSERT(). 190 191 192 @param SectionType Indicates the FFS section type to search for within 193 the FFS file that the currently executing module 194 was loaded from. 195 @param SectionInstance Indicates which section instance to retrieve within 196 the FFS file that the currently executing module 197 was loaded from. 198 @param Buffer On output, a pointer to a callee allocated buffer 199 containing the FFS file section that was found. 200 It is the caller's responsibility to free this buffer 201 using FreePool(). 202 @param Size On output, a pointer to the size, in bytes, of Buffer. 203 204 @retval EFI_SUCCESS The specified FFS section was returned. 205 @retval EFI_NOT_FOUND The specified FFS section could not be found. 206 @retval EFI_OUT_OF_RESOURCES There are not enough resources available to retrieve 207 the matching FFS section. 208 @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a 209 device error. 210 @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the 211 firmware volume that contains the matching FFS 212 section does not allow reads. 213 214 **/ 215 EFI_STATUS 216 EFIAPI 217 GetSectionFromFfs ( 218 IN EFI_SECTION_TYPE SectionType, 219 IN UINTN SectionInstance, 220 OUT VOID **Buffer, 221 OUT UINTN *Size 222 ); 223 224 225 /** 226 Get the image file buffer data and buffer size by its device path. 227 228 Access the file either from a firmware volume, from a file system interface, 229 or from the load file interface. 230 231 Allocate memory to store the found image. The caller is responsible to free memory. 232 233 If FilePath is NULL, then NULL is returned. 234 If FileSize is NULL, then NULL is returned. 235 If AuthenticationStatus is NULL, then NULL is returned. 236 237 @param[in] BootPolicy The policy for Open Image File.If TRUE, 238 indicates that the request originates from 239 the boot manager, and that the boot manager is 240 attempting to load FilePath as a boot selection. 241 If FALSE, then FilePath must match an exact 242 file to be loaded. 243 @param[in] FilePath Pointer to the device path of the file that is abstracted to 244 the file buffer. 245 @param[out] FileSize Pointer to the size of the abstracted file buffer. 246 @param[out] AuthenticationStatus Pointer to the authentication status. 247 248 @retval NULL FilePath is NULL, or FileSize is NULL, or AuthenticationStatus is NULL, or the file can't be found. 249 @retval other The abstracted file buffer. The caller is responsible to free memory. 250 **/ 251 VOID * 252 EFIAPI 253 GetFileBufferByFilePath ( 254 IN BOOLEAN BootPolicy, 255 IN CONST EFI_DEVICE_PATH_PROTOCOL *FilePath, 256 OUT UINTN *FileSize, 257 OUT UINT32 *AuthenticationStatus 258 ); 259 260 /** 261 Searches all the available firmware volumes and returns the file device path of first matching 262 FFS section. 263 264 This function searches all the firmware volumes for FFS files with an FFS filename specified by NameGuid. 265 The order that the firmware volumes is searched is not deterministic. For each FFS file found a search 266 is made for FFS sections of type SectionType. 267 268 If SectionType is EFI_SECTION_TE, and the search with an FFS file fails, 269 the search will be retried with a section type of EFI_SECTION_PE32. 270 This function must be called with a TPL <= TPL_NOTIFY. 271 272 If NameGuid is NULL, then ASSERT(). 273 274 @param NameGuid A pointer to to the FFS filename GUID to search for 275 within any of the firmware volumes in the platform. 276 @param SectionType Indicates the FFS section type to search for within 277 the FFS file specified by NameGuid. 278 @param SectionInstance Indicates which section instance within the FFS file 279 specified by NameGuid to retrieve. 280 @param FvFileDevicePath Device path for the target FFS 281 file. 282 283 @retval EFI_SUCCESS The specified file device path of FFS section was returned. 284 @retval EFI_NOT_FOUND The specified file device path of FFS section could not be found. 285 @retval EFI_DEVICE_ERROR The FFS section could not be retrieves due to a 286 device error. 287 @retval EFI_ACCESS_DENIED The FFS section could not be retrieves because the 288 firmware volume that contains the matching FFS section does not 289 allow reads. 290 @retval EFI_INVALID_PARAMETER FvFileDevicePath is NULL. 291 292 **/ 293 EFI_STATUS 294 EFIAPI 295 GetFileDevicePathFromAnyFv ( 296 IN CONST EFI_GUID *NameGuid, 297 IN EFI_SECTION_TYPE SectionType, 298 IN UINTN SectionInstance, 299 OUT EFI_DEVICE_PATH_PROTOCOL **FvFileDevicePath 300 ); 301 302 /** 303 Allocates one or more 4KB pages of a given type from a memory region that is 304 accessible to PEI. 305 306 Allocates the number of 4KB pages of type 'MemoryType' and returns a 307 pointer to the allocated buffer. The buffer returned is aligned on a 4KB 308 boundary. If Pages is 0, then NULL is returned. If there is not enough 309 memory remaining to satisfy the request, then NULL is returned. 310 311 @param[in] MemoryType The memory type to allocate 312 @param[in] Pages The number of 4 KB pages to allocate. 313 314 @return A pointer to the allocated buffer or NULL if allocation fails. 315 316 **/ 317 VOID * 318 EFIAPI 319 AllocatePeiAccessiblePages ( 320 IN EFI_MEMORY_TYPE MemoryType, 321 IN UINTN Pages 322 ); 323 324 #endif 325