]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Library/HobLib.h
Synchronize function comment in
[mirror_edk2.git] / MdePkg / Include / Library / HobLib.h
1 /** @file
2 Provides services to create and parse HOBs. Only available for PEI
3 and DXE module types.
4
5 The HOB Library supports the efficient creation and searching of HOBs
6 defined in the PI Specification.
7 A HOB is a Hand-Off Block, defined in the Framework architecture, that
8 allows the PEI phase to pass information to the DXE phase. HOBs are position
9 independent and can be relocated easily to different memory memory locations.
10
11 Copyright (c) 2006 - 2008, Intel Corporation<BR>
12 All rights reserved. This program and the accompanying materials
13 are licensed and made available under the terms and conditions of the BSD License
14 which accompanies this distribution. The full text of the license may be found at
15 http://opensource.org/licenses/bsd-license.php
16
17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19
20 **/
21
22 #ifndef __HOB_LIB_H__
23 #define __HOB_LIB_H__
24
25 /**
26 Returns the pointer to the HOB list.
27
28 This function returns the pointer to first HOB in the list.
29 For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer
30 to the HOB list. For the DXE phase, the HOB list pointer can be retrieved through
31 the EFI System Table by looking up theHOB list GUID in the System Configuration Table.
32 Since the System Configuration Table does not exist that the time the DXE Core is
33 launched, the DXE Core uses a global variable from the DXE Core Entry Point Library
34 to manage the pointer to the HOB list.
35
36 If the pointer to the HOB list is NULL, then ASSERT().
37
38 @return The pointer to the HOB list.
39
40 **/
41 VOID *
42 EFIAPI
43 GetHobList (
44 VOID
45 );
46
47 /**
48 Returns the next instance of a HOB type from the starting HOB.
49
50 This function searches the first instance of a HOB type from the starting HOB pointer.
51 If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
52 In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
53 unconditionally: it returns HobStart back if HobStart itself meets the requirement;
54 caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
55
56 If HobStart is NULL, then ASSERT().
57
58 @param Type The HOB type to return.
59 @param HobStart The starting HOB pointer to search from.
60
61 @return The next instance of a HOB type from the starting HOB.
62
63 **/
64 VOID *
65 EFIAPI
66 GetNextHob (
67 IN UINT16 Type,
68 IN CONST VOID *HobStart
69 );
70
71 /**
72 Returns the first instance of a HOB type among the whole HOB list.
73
74 This function searches the first instance of a HOB type among the whole HOB list.
75 If there does not exist such HOB type in the HOB list, it will return NULL.
76
77 If the pointer to the HOB list is NULL, then ASSERT().
78
79 @param Type The HOB type to return.
80
81 @return The next instance of a HOB type from the starting HOB.
82
83 **/
84 VOID *
85 EFIAPI
86 GetFirstHob (
87 IN UINT16 Type
88 );
89
90 /**
91 Returns the next instance of the matched GUID HOB from the starting HOB.
92
93 This function searches the first instance of a HOB from the starting HOB pointer.
94 Such HOB should satisfy two conditions:
95 its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
96 If there does not exist such HOB from the starting HOB pointer, it will return NULL.
97 Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
98 to extract the data section and its size info respectively.
99 In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
100 unconditionally: it returns HobStart back if HobStart itself meets the requirement;
101 caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
102
103 If Guid is NULL, then ASSERT().
104 If HobStart is NULL, then ASSERT().
105
106 @param Guid The GUID to match with in the HOB list.
107 @param HobStart A pointer to a Guid.
108
109 @return The next instance of the matched GUID HOB from the starting HOB.
110
111 **/
112 VOID *
113 EFIAPI
114 GetNextGuidHob (
115 IN CONST EFI_GUID *Guid,
116 IN CONST VOID *HobStart
117 );
118
119 /**
120 Returns the first instance of the matched GUID HOB among the whole HOB list.
121
122 This function searches the first instance of a HOB among the whole HOB list.
123 Such HOB should satisfy two conditions:
124 its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
125 If there does not exist such HOB from the starting HOB pointer, it will return NULL.
126 Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
127 to extract the data section and its size info respectively.
128
129 If the pointer to the HOB list is NULL, then ASSERT().
130 If Guid is NULL, then ASSERT().
131
132 @param Guid The GUID to match with in the HOB list.
133
134 @return The first instance of the matched GUID HOB among the whole HOB list.
135
136 **/
137 VOID *
138 EFIAPI
139 GetFirstGuidHob (
140 IN CONST EFI_GUID *Guid
141 );
142
143 /**
144 Get the system boot mode from the HOB list.
145
146 This function returns the system boot mode information from the
147 PHIT HOB in HOB list.
148
149 If the pointer to the HOB list is NULL, then ASSERT().
150
151 @param VOID
152
153 @return The Boot Mode.
154
155 **/
156 EFI_BOOT_MODE
157 EFIAPI
158 GetBootModeHob (
159 VOID
160 );
161
162 /**
163 Builds a HOB for a loaded PE32 module.
164
165 This function builds a HOB for a loaded PE32 module.
166 It can only be invoked during PEI phase;
167 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
168
169 If ModuleName is NULL, then ASSERT().
170 If there is no additional space for HOB creation, then ASSERT().
171
172 @param ModuleName The GUID File Name of the module.
173 @param MemoryAllocationModule The 64 bit physical address of the module.
174 @param ModuleLength The length of the module in bytes.
175 @param EntryPoint The 64 bit physical address of the module entry point.
176
177 **/
178 VOID
179 EFIAPI
180 BuildModuleHob (
181 IN CONST EFI_GUID *ModuleName,
182 IN EFI_PHYSICAL_ADDRESS MemoryAllocationModule,
183 IN UINT64 ModuleLength,
184 IN EFI_PHYSICAL_ADDRESS EntryPoint
185 );
186
187 /**
188 Builds a HOB that describes a chunk of system memory.
189
190 This function builds a HOB that describes a chunk of system memory.
191 It can only be invoked during PEI phase;
192 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
193
194 If there is no additional space for HOB creation, then ASSERT().
195
196 @param ResourceType The type of resource described by this HOB.
197 @param ResourceAttribute The resource attributes of the memory described by this HOB.
198 @param PhysicalStart The 64 bit physical address of memory described by this HOB.
199 @param NumberOfBytes The length of the memory described by this HOB in bytes.
200
201 **/
202 VOID
203 EFIAPI
204 BuildResourceDescriptorHob (
205 IN EFI_RESOURCE_TYPE ResourceType,
206 IN EFI_RESOURCE_ATTRIBUTE_TYPE ResourceAttribute,
207 IN EFI_PHYSICAL_ADDRESS PhysicalStart,
208 IN UINT64 NumberOfBytes
209 );
210
211 /**
212 Builds a customized HOB tagged with a GUID for identification and returns
213 the start address of GUID HOB data.
214
215 This function builds a customized HOB tagged with a GUID for identification
216 and returns the start address of GUID HOB data so that caller can fill the customized data.
217 The HOB Header and Name field is already stripped.
218 It can only be invoked during PEI phase;
219 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
220
221 If Guid is NULL, then ASSERT().
222 If there is no additional space for HOB creation, then ASSERT().
223 If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
224
225 @param Guid The GUID to tag the customized HOB.
226 @param DataLength The size of the data payload for the GUID HOB.
227
228 @return The start address of GUID HOB data.
229
230 **/
231 VOID *
232 EFIAPI
233 BuildGuidHob (
234 IN CONST EFI_GUID *Guid,
235 IN UINTN DataLength
236 );
237
238 /**
239 Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB
240 data field, and returns the start address of the GUID HOB data.
241
242 This function builds a customized HOB tagged with a GUID for identification and copies the input
243 data to the HOB data field and returns the start address of the GUID HOB data. It can only be
244 invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
245 The HOB Header and Name field is already stripped.
246 It can only be invoked during PEI phase;
247 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
248
249 If Guid is NULL, then ASSERT().
250 If Data is NULL and DataLength > 0, then ASSERT().
251 If there is no additional space for HOB creation, then ASSERT().
252 If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
253
254 @param Guid The GUID to tag the customized HOB.
255 @param Data The data to be copied into the data field of the GUID HOB.
256 @param DataLength The size of the data payload for the GUID HOB.
257
258 @return The start address of GUID HOB data.
259
260 **/
261 VOID *
262 EFIAPI
263 BuildGuidDataHob (
264 IN CONST EFI_GUID *Guid,
265 IN VOID *Data,
266 IN UINTN DataLength
267 );
268
269 /**
270 Builds a Firmware Volume HOB.
271
272 This function builds a Firmware Volume HOB.
273 It can only be invoked during PEI phase;
274 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
275
276 If there is no additional space for HOB creation, then ASSERT().
277
278 @param BaseAddress The base address of the Firmware Volume.
279 @param Length The size of the Firmware Volume in bytes.
280
281 **/
282 VOID
283 EFIAPI
284 BuildFvHob (
285 IN EFI_PHYSICAL_ADDRESS BaseAddress,
286 IN UINT64 Length
287 );
288
289 /**
290 Builds a EFI_HOB_TYPE_FV2 HOB.
291
292 This function builds a EFI_HOB_TYPE_FV2 HOB.
293 It can only be invoked during PEI phase;
294 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
295
296 If there is no additional space for HOB creation, then ASSERT().
297
298 @param BaseAddress The base address of the Firmware Volume.
299 @param Length The size of the Firmware Volume in bytes.
300 @param FvName The name of the Firmware Volume.
301 @param FileName The name of the file.
302
303 **/
304 VOID
305 EFIAPI
306 BuildFv2Hob (
307 IN EFI_PHYSICAL_ADDRESS BaseAddress,
308 IN UINT64 Length,
309 IN CONST EFI_GUID *FvName,
310 IN CONST EFI_GUID *FileName
311 );
312
313 /**
314 Builds a Capsule Volume HOB.
315
316 This function builds a Capsule Volume HOB.
317 It can only be invoked during PEI phase;
318 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
319
320 If there is no additional space for HOB creation, then ASSERT().
321
322 @param BaseAddress The base address of the Capsule Volume.
323 @param Length The size of the Capsule Volume in bytes.
324
325 **/
326 VOID
327 EFIAPI
328 BuildCvHob (
329 IN EFI_PHYSICAL_ADDRESS BaseAddress,
330 IN UINT64 Length
331 );
332
333 /**
334 Builds a HOB for the CPU.
335
336 This function builds a HOB for the CPU.
337 It can only be invoked during PEI phase;
338 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
339
340 If there is no additional space for HOB creation, then ASSERT().
341
342 @param SizeOfMemorySpace The maximum physical memory addressability of the processor.
343 @param SizeOfIoSpace The maximum physical I/O addressability of the processor.
344
345 **/
346 VOID
347 EFIAPI
348 BuildCpuHob (
349 IN UINT8 SizeOfMemorySpace,
350 IN UINT8 SizeOfIoSpace
351 );
352
353 /**
354 Builds a HOB for the Stack.
355
356 This function builds a HOB for the stack.
357 It can only be invoked during PEI phase;
358 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
359
360 If there is no additional space for HOB creation, then ASSERT().
361
362 @param BaseAddress The 64 bit physical address of the Stack.
363 @param Length The length of the stack in bytes.
364
365 **/
366 VOID
367 EFIAPI
368 BuildStackHob (
369 IN EFI_PHYSICAL_ADDRESS BaseAddress,
370 IN UINT64 Length
371 );
372
373 /**
374 Builds a HOB for the BSP store.
375
376 This function builds a HOB for BSP store.
377 It can only be invoked during PEI phase;
378 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
379
380 If there is no additional space for HOB creation, then ASSERT().
381
382 @param BaseAddress The 64 bit physical address of the BSP.
383 @param Length The length of the BSP store in bytes.
384 @param MemoryType Type of memory allocated by this HOB.
385
386 **/
387 VOID
388 EFIAPI
389 BuildBspStoreHob (
390 IN EFI_PHYSICAL_ADDRESS BaseAddress,
391 IN UINT64 Length,
392 IN EFI_MEMORY_TYPE MemoryType
393 );
394
395 /**
396 Builds a HOB for the memory allocation.
397
398 This function builds a HOB for the memory allocation.
399 It can only be invoked during PEI phase;
400 for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
401
402 If there is no additional space for HOB creation, then ASSERT().
403
404 @param BaseAddress The 64 bit physical address of the memory.
405 @param Length The length of the memory allocation in bytes.
406 @param MemoryType Type of memory allocated by this HOB.
407
408 **/
409 VOID
410 EFIAPI
411 BuildMemoryAllocationHob (
412 IN EFI_PHYSICAL_ADDRESS BaseAddress,
413 IN UINT64 Length,
414 IN EFI_MEMORY_TYPE MemoryType
415 );
416
417 /**
418 Returns the type of a HOB.
419
420 This macro returns the HobType field from the HOB header for the
421 HOB specified by Hob.
422
423 @param Hob A pointer to a HOB.
424
425 @return HobType
426
427 **/
428 #define GET_HOB_TYPE(Hob) ((Hob).Header->HobType)
429
430 /**
431 Returns the length, in bytes, of a HOB.
432
433 This macro returns the HobLength field from the HOB header for the
434 HOB specified by Hob.
435
436 @param Hob A pointer to a HOB.
437
438 @return HobLength
439
440 **/
441 #define GET_HOB_LENGTH(Hob) ((Hob).Header->HobLength)
442
443 /**
444 Returns a pointer to the next HOB in the HOB list.
445
446 This macro returns a pointer to HOB that follows the
447 HOB specified by Hob in the HOB List.
448
449 @param Hob A pointer to a HOB.
450
451 @return A pointer to the next HOB in the HOB list.
452
453 **/
454 #define GET_NEXT_HOB(Hob) ((Hob).Raw + GET_HOB_LENGTH (Hob))
455
456 /**
457 Determines if a HOB is the last HOB in the HOB list.
458
459 This macro determine if the HOB specified by Hob is the
460 last HOB in the HOB list. If Hob is last HOB in the HOB list,
461 then TRUE is returned. Otherwise, FALSE is returned.
462
463 @param Hob A pointer to a HOB.
464
465 @retval TRUE The HOB specified by Hob is the last HOB in the HOB list.
466 @retval FALSE The HOB specified by Hob is not the last HOB in the HOB list.
467
468 **/
469 #define END_OF_HOB_LIST(Hob) (GET_HOB_TYPE (Hob) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST)
470
471 /**
472 Returns a pointer to data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
473
474 This macro returns a pointer to the data buffer in a HOB specified by Hob.
475 Hob is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
476
477 @param Hob A pointer to a HOB.
478
479 @return A pointer to the data buffer in a HOB
480
481 **/
482 #define GET_GUID_HOB_DATA(GuidHob) ((VOID *) (((UINT8 *) &((GuidHob)->Name)) + sizeof (EFI_GUID)))
483
484 /**
485 Returns the size of the data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
486
487 This macro returns the size, in bytes, of the data buffer in a HOB specified by Hob.
488 Hob is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
489
490 @param Hob A pointer to a HOB.
491
492 @return The size of the data buffer
493 **/
494 #define GET_GUID_HOB_DATA_SIZE(GuidHob) (((GuidHob)->Header).HobLength - sizeof (EFI_HOB_GUID_TYPE))
495
496 #endif