VirtualBox

source: vbox/trunk/src/VBox/Devices/EFI/FirmwareNew/MdePkg/Include/Library/DxeServicesLib.h@ 80721

Last change on this file since 80721 was 80721, checked in by vboxsync, 5 years ago

Devices/EFI/FirmwareNew: Start upgrade process to edk2-stable201908 (compiles on Windows and works to some extent), bugref:4643
  • Property svn:eol-style set to native
File size: 16.6 KB
Line 
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
5Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
6(C) Copyright 2015 Hewlett Packard Enterprise Development LP<BR>
7SPDX-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**/
53EFI_STATUS
54EFIAPI
55GetSectionFromAnyFvByFileType (
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**/
107EFI_STATUS
108EFIAPI
109GetSectionFromAnyFv (
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**/
162EFI_STATUS
163EFIAPI
164GetSectionFromFv (
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 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**/
215EFI_STATUS
216EFIAPI
217GetSectionFromFfs (
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**/
251VOID *
252EFIAPI
253GetFileBufferByFilePath (
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**/
293EFI_STATUS
294EFIAPI
295GetFileDevicePathFromAnyFv (
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**/
317VOID *
318EFIAPI
319AllocatePeiAccessiblePages (
320 IN EFI_MEMORY_TYPE MemoryType,
321 IN UINTN Pages
322 );
323
324#endif
Note: See TracBrowser for help on using the repository browser.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette