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 locations.
  10
  11 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  12 SPDX-License-Identifier: BSD-2-Clause-Patent
  13
  14 **/
  15
  16 #ifndef __HOB_LIB_H__
  17 #define __HOB_LIB_H__
  18
  19 /**
  20   Returns the pointer to the HOB list.
  21
  22   This function returns the pointer to first HOB in the list.
  23   For PEI phase, the PEI service GetHobList() can be used to retrieve the pointer
  24   to the HOB list.  For the DXE phase, the HOB list pointer can be retrieved through
  25   the EFI System Table by looking up theHOB list GUID in the System Configuration Table.
  26   Since the System Configuration Table does not exist that the time the DXE Core is
  27   launched, the DXE Core uses a global variable from the DXE Core Entry Point Library
  28   to manage the pointer to the HOB list.
  29
  30   If the pointer to the HOB list is NULL, then ASSERT().
  31
  32   @return The pointer to the HOB list.
  33
  34 **/
  35 VOID *
  36 EFIAPI
  37 GetHobList (
  38   VOID
  39   );
  40
  41 /**
  42   Returns the next instance of a HOB type from the starting HOB.
  43
  44   This function searches the first instance of a HOB type from the starting HOB pointer.
  45   If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  46   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  47   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  48   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  49
  50   If HobStart is NULL, then ASSERT().
  51
  52   @param  Type          The HOB type to return.
  53   @param  HobStart      The starting HOB pointer to search from.
  54
  55   @return The next instance of a HOB type from the starting HOB.
  56
  57 **/
  58 VOID *
  59 EFIAPI
  60 GetNextHob (
  61   IN UINT16      Type,
  62   IN CONST VOID  *HobStart
  63   );
  64
  65 /**
  66   Returns the first instance of a HOB type among the whole HOB list.
  67
  68   This function searches the first instance of a HOB type among the whole HOB list.
  69   If there does not exist such HOB type in the HOB list, it will return NULL.
  70
  71   If the pointer to the HOB list is NULL, then ASSERT().
  72
  73   @param  Type          The HOB type to return.
  74
  75   @return The next instance of a HOB type from the starting HOB.
  76
  77 **/
  78 VOID *
  79 EFIAPI
  80 GetFirstHob (
  81   IN UINT16  Type
  82   );
  83
  84 /**
  85   Returns the next instance of the matched GUID HOB from the starting HOB.
  86
  87   This function searches the first instance of a HOB from the starting HOB pointer.
  88   Such HOB should satisfy two conditions:
  89   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
  90   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
  91   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
  92   to extract the data section and its size info respectively.
  93   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  94   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  95   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  96
  97   If Guid is NULL, then ASSERT().
  98   If HobStart is NULL, then ASSERT().
  99
 100   @param  Guid          The GUID to match with in the HOB list.
 101   @param  HobStart      A pointer to a Guid.
 102
 103   @return The next instance of the matched GUID HOB from the starting HOB.
 104
 105 **/
 106 VOID *
 107 EFIAPI
 108 GetNextGuidHob (
 109   IN CONST EFI_GUID  *Guid,
 110   IN CONST VOID      *HobStart
 111   );
 112
 113 /**
 114   Returns the first instance of the matched GUID HOB among the whole HOB list.
 115
 116   This function searches the first instance of a HOB among the whole HOB list.
 117   Such HOB should satisfy two conditions:
 118   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 119   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 120   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 121   to extract the data section and its size info respectively.
 122
 123   If the pointer to the HOB list is NULL, then ASSERT().
 124   If Guid is NULL, then ASSERT().
 125
 126   @param  Guid          The GUID to match with in the HOB list.
 127
 128   @return The first instance of the matched GUID HOB among the whole HOB list.
 129
 130 **/
 131 VOID *
 132 EFIAPI
 133 GetFirstGuidHob (
 134   IN CONST EFI_GUID  *Guid
 135   );
 136
 137 /**
 138   Get the system boot mode from the HOB list.
 139
 140   This function returns the system boot mode information from the
 141   PHIT HOB in HOB list.
 142
 143   If the pointer to the HOB list is NULL, then ASSERT().
 144
 145   @param  VOID
 146
 147   @return The Boot Mode.
 148
 149 **/
 150 EFI_BOOT_MODE
 151 EFIAPI
 152 GetBootModeHob (
 153   VOID
 154   );
 155
 156 /**
 157   Builds a HOB for a loaded PE32 module.
 158
 159   This function builds a HOB for a loaded PE32 module.
 160   It can only be invoked during PEI phase;
 161   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 162
 163   If ModuleName is NULL, then ASSERT().
 164   If there is no additional space for HOB creation, then ASSERT().
 165
 166   @param  ModuleName              The GUID File Name of the module.
 167   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 168   @param  ModuleLength            The length of the module in bytes.
 169   @param  EntryPoint              The 64 bit physical address of the module entry point.
 170
 171 **/
 172 VOID
 173 EFIAPI
 174 BuildModuleHob (
 175   IN CONST EFI_GUID        *ModuleName,
 176   IN EFI_PHYSICAL_ADDRESS  MemoryAllocationModule,
 177   IN UINT64                ModuleLength,
 178   IN EFI_PHYSICAL_ADDRESS  EntryPoint
 179   );
 180
 181 /**
 182   Builds a HOB that describes a chunk of system memory with Owner GUID.
 183
 184   This function builds a HOB that describes a chunk of system memory.
 185   It can only be invoked during PEI phase;
 186   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 187
 188   If there is no additional space for HOB creation, then ASSERT().
 189
 190   @param  ResourceType        The type of resource described by this HOB.
 191   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 192   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 193   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 194   @param  OwnerGUID           GUID for the owner of this resource.
 195
 196 **/
 197 VOID
 198 EFIAPI
 199 BuildResourceDescriptorWithOwnerHob (
 200   IN EFI_RESOURCE_TYPE            ResourceType,
 201   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 202   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 203   IN UINT64                       NumberOfBytes,
 204   IN EFI_GUID                     *OwnerGUID
 205   );
 206
 207 /**
 208   Builds a HOB that describes a chunk of system memory.
 209
 210   This function builds a HOB that describes a chunk of system memory.
 211   It can only be invoked during PEI phase;
 212   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 213
 214   If there is no additional space for HOB creation, then ASSERT().
 215
 216   @param  ResourceType        The type of resource described by this HOB.
 217   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 218   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 219   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 220
 221 **/
 222 VOID
 223 EFIAPI
 224 BuildResourceDescriptorHob (
 225   IN EFI_RESOURCE_TYPE            ResourceType,
 226   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 227   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 228   IN UINT64                       NumberOfBytes
 229   );
 230
 231 /**
 232   Builds a customized HOB tagged with a GUID for identification and returns
 233   the start address of GUID HOB data.
 234
 235   This function builds a customized HOB tagged with a GUID for identification
 236   and returns the start address of GUID HOB data so that caller can fill the customized data.
 237   The HOB Header and Name field is already stripped.
 238   It can only be invoked during PEI phase;
 239   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 240
 241   If Guid is NULL, then ASSERT().
 242   If there is no additional space for HOB creation, then ASSERT().
 243   If DataLength > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 244   HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8.
 245
 246   @param  Guid          The GUID to tag the customized HOB.
 247   @param  DataLength    The size of the data payload for the GUID HOB.
 248
 249   @retval  NULL         The GUID HOB could not be allocated.
 250   @retval  others       The start address of GUID HOB data.
 251
 252 **/
 253 VOID *
 254 EFIAPI
 255 BuildGuidHob (
 256   IN CONST EFI_GUID  *Guid,
 257   IN UINTN           DataLength
 258   );
 259
 260 /**
 261   Builds a customized HOB tagged with a GUID for identification, copies the input data to the HOB
 262   data field, and returns the start address of the GUID HOB data.
 263
 264   This function builds a customized HOB tagged with a GUID for identification and copies the input
 265   data to the HOB data field and returns the start address of the GUID HOB data.  It can only be
 266   invoked during PEI phase; for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 267   The HOB Header and Name field is already stripped.
 268   It can only be invoked during PEI phase;
 269   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 270
 271   If Guid is NULL, then ASSERT().
 272   If Data is NULL and DataLength > 0, then ASSERT().
 273   If there is no additional space for HOB creation, then ASSERT().
 274   If DataLength > (0xFFF8 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 275   HobLength is UINT16 and multiples of 8 bytes, so the max HobLength is 0xFFF8.
 276
 277   @param  Guid          The GUID to tag the customized HOB.
 278   @param  Data          The data to be copied into the data field of the GUID HOB.
 279   @param  DataLength    The size of the data payload for the GUID HOB.
 280
 281   @retval  NULL         The GUID HOB could not be allocated.
 282   @retval  others       The start address of GUID HOB data.
 283
 284 **/
 285 VOID *
 286 EFIAPI
 287 BuildGuidDataHob (
 288   IN CONST EFI_GUID  *Guid,
 289   IN VOID            *Data,
 290   IN UINTN           DataLength
 291   );
 292
 293 /**
 294   Builds a Firmware Volume HOB.
 295
 296   This function builds a Firmware Volume 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   If the FvImage buffer is not at its required alignment, then ASSERT().
 302
 303   @param  BaseAddress   The base address of the Firmware Volume.
 304   @param  Length        The size of the Firmware Volume in bytes.
 305
 306 **/
 307 VOID
 308 EFIAPI
 309 BuildFvHob (
 310   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
 311   IN UINT64                Length
 312   );
 313
 314 /**
 315   Builds a EFI_HOB_TYPE_FV2 HOB.
 316
 317   This function builds a EFI_HOB_TYPE_FV2 HOB.
 318   It can only be invoked during PEI phase;
 319   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 320
 321   If there is no additional space for HOB creation, then ASSERT().
 322   If the FvImage buffer is not at its required alignment, then ASSERT().
 323
 324   @param  BaseAddress   The base address of the Firmware Volume.
 325   @param  Length        The size of the Firmware Volume in bytes.
 326   @param  FvName        The name of the Firmware Volume.
 327   @param  FileName      The name of the file.
 328
 329 **/
 330 VOID
 331 EFIAPI
 332 BuildFv2Hob (
 333   IN          EFI_PHYSICAL_ADDRESS  BaseAddress,
 334   IN          UINT64                Length,
 335   IN CONST    EFI_GUID              *FvName,
 336   IN CONST    EFI_GUID              *FileName
 337   );
 338
 339 /**
 340   Builds a EFI_HOB_TYPE_FV3 HOB.
 341
 342   This function builds a EFI_HOB_TYPE_FV3 HOB.
 343   It can only be invoked during PEI phase;
 344   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 345
 346   If there is no additional space for HOB creation, then ASSERT().
 347   If the FvImage buffer is not at its required alignment, then ASSERT().
 348
 349   @param BaseAddress            The base address of the Firmware Volume.
 350   @param Length                 The size of the Firmware Volume in bytes.
 351   @param AuthenticationStatus   The authentication status.
 352   @param ExtractedFv            TRUE if the FV was extracted as a file within
 353                                 another firmware volume. FALSE otherwise.
 354   @param FvName                 The name of the Firmware Volume.
 355                                 Valid only if IsExtractedFv is TRUE.
 356   @param FileName               The name of the file.
 357                                 Valid only if IsExtractedFv is TRUE.
 358
 359 **/
 360 VOID
 361 EFIAPI
 362 BuildFv3Hob (
 363   IN          EFI_PHYSICAL_ADDRESS  BaseAddress,
 364   IN          UINT64                Length,
 365   IN          UINT32                AuthenticationStatus,
 366   IN          BOOLEAN               ExtractedFv,
 367   IN CONST    EFI_GUID              *FvName  OPTIONAL,
 368   IN CONST    EFI_GUID              *FileName OPTIONAL
 369   );
 370
 371 /**
 372   Builds a Capsule Volume HOB.
 373
 374   This function builds a Capsule Volume HOB.
 375   It can only be invoked during PEI phase;
 376   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 377
 378   If the platform does not support Capsule Volume HOBs, then ASSERT().
 379   If there is no additional space for HOB creation, then ASSERT().
 380
 381   @param  BaseAddress   The base address of the Capsule Volume.
 382   @param  Length        The size of the Capsule Volume in bytes.
 383
 384 **/
 385 VOID
 386 EFIAPI
 387 BuildCvHob (
 388   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
 389   IN UINT64                Length
 390   );
 391
 392 /**
 393   Builds a HOB for the CPU.
 394
 395   This function builds a HOB for the CPU.
 396   It can only be invoked during PEI phase;
 397   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 398
 399   If there is no additional space for HOB creation, then ASSERT().
 400
 401   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 402   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 403
 404 **/
 405 VOID
 406 EFIAPI
 407 BuildCpuHob (
 408   IN UINT8  SizeOfMemorySpace,
 409   IN UINT8  SizeOfIoSpace
 410   );
 411
 412 /**
 413   Builds a HOB for the Stack.
 414
 415   This function builds a HOB for the stack.
 416   It can only be invoked during PEI phase;
 417   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 418
 419   If there is no additional space for HOB creation, then ASSERT().
 420
 421   @param  BaseAddress   The 64 bit physical address of the Stack.
 422   @param  Length        The length of the stack in bytes.
 423
 424 **/
 425 VOID
 426 EFIAPI
 427 BuildStackHob (
 428   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
 429   IN UINT64                Length
 430   );
 431
 432 /**
 433   Builds a HOB for the BSP store.
 434
 435   This function builds a HOB for BSP store.
 436   It can only be invoked during PEI phase;
 437   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 438
 439   If there is no additional space for HOB creation, then ASSERT().
 440
 441   @param  BaseAddress   The 64 bit physical address of the BSP.
 442   @param  Length        The length of the BSP store in bytes.
 443   @param  MemoryType    Type of memory allocated by this HOB.
 444
 445 **/
 446 VOID
 447 EFIAPI
 448 BuildBspStoreHob (
 449   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
 450   IN UINT64                Length,
 451   IN EFI_MEMORY_TYPE       MemoryType
 452   );
 453
 454 /**
 455   Builds a HOB for the memory allocation.
 456
 457   This function builds a HOB for the memory allocation.
 458   It can only be invoked during PEI phase;
 459   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 460
 461   If there is no additional space for HOB creation, then ASSERT().
 462
 463   @param  BaseAddress   The 64 bit physical address of the memory.
 464   @param  Length        The length of the memory allocation in bytes.
 465   @param  MemoryType    Type of memory allocated by this HOB.
 466
 467 **/
 468 VOID
 469 EFIAPI
 470 BuildMemoryAllocationHob (
 471   IN EFI_PHYSICAL_ADDRESS  BaseAddress,
 472   IN UINT64                Length,
 473   IN EFI_MEMORY_TYPE       MemoryType
 474   );
 475
 476 /**
 477   Returns the type of a HOB.
 478
 479   This macro returns the HobType field from the HOB header for the
 480   HOB specified by HobStart.
 481
 482   @param  HobStart   A pointer to a HOB.
 483
 484   @return HobType.
 485
 486 **/
 487 #define GET_HOB_TYPE(HobStart) \
 488   ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobType)
 489
 490 /**
 491   Returns the length, in bytes, of a HOB.
 492
 493   This macro returns the HobLength field from the HOB header for the
 494   HOB specified by HobStart.
 495
 496   @param  HobStart   A pointer to a HOB.
 497
 498   @return HobLength.
 499
 500 **/
 501 #define GET_HOB_LENGTH(HobStart) \
 502   ((*(EFI_HOB_GENERIC_HEADER **)&(HobStart))->HobLength)
 503
 504 /**
 505   Returns a pointer to the next HOB in the HOB list.
 506
 507   This macro returns a pointer to HOB that follows the
 508   HOB specified by HobStart in the HOB List.
 509
 510   @param  HobStart   A pointer to a HOB.
 511
 512   @return A pointer to the next HOB in the HOB list.
 513
 514 **/
 515 #define GET_NEXT_HOB(HobStart) \
 516   (VOID *)(*(UINT8 **)&(HobStart) + GET_HOB_LENGTH (HobStart))
 517
 518 /**
 519   Determines if a HOB is the last HOB in the HOB list.
 520
 521   This macro determine if the HOB specified by HobStart is the
 522   last HOB in the HOB list.  If HobStart is last HOB in the HOB list,
 523   then TRUE is returned.  Otherwise, FALSE is returned.
 524
 525   @param  HobStart   A pointer to a HOB.
 526
 527   @retval TRUE       The HOB specified by HobStart is the last HOB in the HOB list.
 528   @retval FALSE      The HOB specified by HobStart is not the last HOB in the HOB list.
 529
 530 **/
 531 #define END_OF_HOB_LIST(HobStart)  (GET_HOB_TYPE (HobStart) == (UINT16)EFI_HOB_TYPE_END_OF_HOB_LIST)
 532
 533 /**
 534   Returns a pointer to data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 535
 536   This macro returns a pointer to the data buffer in a HOB specified by HobStart.
 537   HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 538
 539   @param   GuidHob   A pointer to a HOB.
 540
 541   @return  A pointer to the data buffer in a HOB.
 542
 543 **/
 544 #define GET_GUID_HOB_DATA(HobStart) \
 545   (VOID *)(*(UINT8 **)&(HobStart) + sizeof (EFI_HOB_GUID_TYPE))
 546
 547 /**
 548   Returns the size of the data buffer from a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 549
 550   This macro returns the size, in bytes, of the data buffer in a HOB specified by HobStart.
 551   HobStart is assumed to be a HOB of type EFI_HOB_TYPE_GUID_EXTENSION.
 552
 553   @param   GuidHob   A pointer to a HOB.
 554
 555   @return  The size of the data buffer.
 556 **/
 557 #define GET_GUID_HOB_DATA_SIZE(HobStart) \
 558   (UINT16)(GET_HOB_LENGTH (HobStart) - sizeof (EFI_HOB_GUID_TYPE))
 559
 560 #endif