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 - 2012, Intel Corporation. All rights reserved.<BR>
  12 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 > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 224   HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8.
 225
 226   @param  Guid          The GUID to tag the customized HOB.
 227   @param  DataLength    The size of the data payload for the GUID HOB.
 228
 229   @retval  NULL         The GUID HOB could not be allocated.
 230   @retval  others       The start address of GUID HOB data.
 231
 232 **/
 233 VOID *
 234 EFIAPI
 235 BuildGuidHob (
 236   IN CONST EFI_GUID              *Guid,
 237   IN UINTN                       DataLength
 238   );
 239
 240 /**
 241   Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB
 242   data field, and returns the start address of the GUID HOB data.
 243
 244   This function builds a customized HOB tagged with a GUID for identification and copies the input
 245   data to the HOB data field and returns the start address of the GUID HOB data.  It can only be
 246   invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 247   The HOB Header and Name field is already stripped.
 248   It can only be invoked during PEI phase;
 249   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 250
 251   If Guid is NULL, then ASSERT().
 252   If Data is NULL and DataLength > 0, then ASSERT().
 253   If there is no additional space for HOB creation, then ASSERT().
 254   If DataLength > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 255   HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8.
 256
 257   @param  Guid          The GUID to tag the customized HOB.
 258   @param  Data          The data to be copied into the data field of the GUID HOB.
 259   @param  DataLength    The size of the data payload for the GUID HOB.
 260
 261   @retval  NULL         The GUID HOB could not be allocated.
 262   @retval  others       The start address of GUID HOB data.
 263
 264 **/
 265 VOID *
 266 EFIAPI
 267 BuildGuidDataHob (
 268   IN CONST EFI_GUID              *Guid,
 269   IN VOID                        *Data,
 270   IN UINTN                       DataLength
 271   );
 272
 273 /**
 274   Builds a Firmware Volume HOB.
 275
 276   This function builds a Firmware Volume HOB.
 277   It can only be invoked during PEI phase;
 278   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 279
 280   If there is no additional space for HOB creation, then ASSERT().
 281
 282   @param  BaseAddress   The base address of the Firmware Volume.
 283   @param  Length        The size of the Firmware Volume in bytes.
 284
 285 **/
 286 VOID
 287 EFIAPI
 288 BuildFvHob (
 289   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 290   IN UINT64                      Length
 291   );
 292
 293 /**
 294   Builds a EFI_HOB_TYPE_FV2 HOB.
 295
 296   This function builds a EFI_HOB_TYPE_FV2 HOB.
 297   It can only be invoked during PEI phase;
 298   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 299
 300   If there is no additional space for HOB creation, then ASSERT().
 301
 302   @param  BaseAddress   The base address of the Firmware Volume.
 303   @param  Length        The size of the Firmware Volume in bytes.
 304   @param  FvName        The name of the Firmware Volume.
 305   @param  FileName      The name of the file.
 306
 307 **/
 308 VOID
 309 EFIAPI
 310 BuildFv2Hob (
 311   IN          EFI_PHYSICAL_ADDRESS        BaseAddress,
 312   IN          UINT64                      Length,
 313   IN CONST    EFI_GUID                    *FvName,
 314   IN CONST    EFI_GUID                    *FileName
 315   );
 316
 317 /**
 318   Builds a Capsule Volume HOB.
 319
 320   This function builds a Capsule Volume HOB.
 321   It can only be invoked during PEI phase;
 322   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 323
 324   If the platform does not support Capsule Volume HOBs, then ASSERT().
 325   If there is no additional space for HOB creation, then ASSERT().
 326
 327   @param  BaseAddress   The base address of the Capsule Volume.
 328   @param  Length        The size of the Capsule Volume in bytes.
 329
 330 **/
 331 VOID
 332 EFIAPI
 333 BuildCvHob (
 334   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 335   IN UINT64                      Length
 336   );
 337
 338 /**
 339   Builds a HOB for the CPU.
 340
 341   This function builds a HOB for the CPU.
 342   It can only be invoked during PEI phase;
 343   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 344
 345   If there is no additional space for HOB creation, then ASSERT().
 346
 347   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 348   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 349
 350 **/
 351 VOID
 352 EFIAPI
 353 BuildCpuHob (
 354   IN UINT8                       SizeOfMemorySpace,
 355   IN UINT8                       SizeOfIoSpace
 356   );
 357
 358 /**
 359   Builds a HOB for the Stack.
 360
 361   This function builds a HOB for the stack.
 362   It can only be invoked during PEI phase;
 363   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 364
 365   If there is no additional space for HOB creation, then ASSERT().
 366
 367   @param  BaseAddress   The 64 bit physical address of the Stack.
 368   @param  Length        The length of the stack in bytes.
 369
 370 **/
 371 VOID
 372 EFIAPI
 373 BuildStackHob (
 374   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 375   IN UINT64                      Length
 376   );
 377
 378 /**
 379   Builds a HOB for the BSP store.
 380
 381   This function builds a HOB for BSP store.
 382   It can only be invoked during PEI phase;
 383   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 384
 385   If there is no additional space for HOB creation, then ASSERT().
 386
 387   @param  BaseAddress   The 64 bit physical address of the BSP.
 388   @param  Length        The length of the BSP store in bytes.
 389   @param  MemoryType    Type of memory allocated by this HOB.
 390
 391 **/
 392 VOID
 393 EFIAPI
 394 BuildBspStoreHob (
 395   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 396   IN UINT64                      Length,
 397   IN EFI_MEMORY_TYPE             MemoryType
 398   );
 399
 400 /**
 401   Builds a HOB for the memory allocation.
 402
 403   This function builds a HOB for the memory allocation.
 404   It can only be invoked during PEI phase;
 405   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 406
 407   If there is no additional space for HOB creation, then ASSERT().
 408
 409   @param  BaseAddress   The 64 bit physical address of the memory.
 410   @param  Length        The length of the memory allocation in bytes.
 411   @param  MemoryType    Type of memory allocated by this HOB.
 412
 413 **/
 414 VOID
 415 EFIAPI
 416 BuildMemoryAllocationHob (
 417   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 418   IN UINT64                      Length,
 419   IN EFI_MEMORY_TYPE             MemoryType
 420   );
 421
 422 /**
 423   Returns the type of a HOB.
 424
 425   This macro returns the HobType field from the HOB header for the
 426   HOB specified by HobStart.
 427
 428   @param  HobStart   A pointer to a HOB.
 429
 430   @return HobType.
 431
 432 **/
 433 #define GET_HOB_TYPE(HobStart) \
 434   ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobType)
 435
 436 /**
 437   Returns the length, in bytes, of a HOB.
 438
 439   This macro returns the HobLength field from the HOB header for the
 440   HOB specified by HobStart.
 441
 442   @param  HobStart   A pointer to a HOB.
 443
 444   @return HobLength.
 445
 446 **/
 447 #define GET_HOB_LENGTH(HobStart) \
 448   ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobLength)
 449
 450 /**
 451   Returns a pointer to the next HOB in the HOB list.
 452
 453   This macro returns a pointer to HOB that follows the
 454   HOB specified by HobStart in the HOB List.
 455
 456   @param  HobStart   A pointer to a HOB.
 457
 458   @return A pointer to the next HOB in the HOB list.
 459
 460 **/
 461 #define GET_NEXT_HOB(HobStart) \
 462   (VOID *)(*(UINT8 **)&(HobStart) + GET_HOB_LENGTH (HobStart))
 463
 464 /**
 465   Determines if a HOB is the last HOB in the HOB list.
 466
 467   This macro determine if the HOB specified by HobStart is the
 468   last HOB in the HOB list.  If HobStart is last HOB in the HOB list,
 469   then TRUE is returned.  Otherwise, FALSE is returned.
 470
 471   @param  HobStart   A pointer to a HOB.
 472
 473   @retval TRUE       The HOB specified by HobStart is the last HOB in the HOB list.
 474   @retval FALSE      The HOB specified by HobStart is not the last HOB in the HOB list.
 475
 476 **/
 477 #define END_OF_HOB_LIST(HobStart)  (GET_HOB_TYPE (HobStart) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST)
 478
 479 /**
 480   Returns a pointer to data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 481
 482   This macro returns a pointer to the data buffer in a HOB specified by HobStart.
 483   HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 484
 485   @param   GuidHob   A pointer to a HOB.
 486
 487   @return  A pointer to the data buffer in a HOB.
 488
 489 **/
 490 #define GET_GUID_HOB_DATA(HobStart) \
 491   (VOID *)(*(UINT8 **)&(HobStart) + sizeof (EFI_HOB_GUID_TYPE))
 492
 493 /**
 494   Returns the size of the data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 495
 496   This macro returns the size, in bytes, of the data buffer in a HOB specified by HobStart.
 497   HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 498
 499   @param   GuidHob   A pointer to a HOB.
 500
 501   @return  The size of the data buffer.
 502 **/
 503 #define GET_GUID_HOB_DATA_SIZE(HobStart) \
 504   (UINT16)(GET_HOB_LENGTH (HobStart) - sizeof (EFI_HOB_GUID_TYPE))
 505
 506 #endif