MdePkg/Library/DxeCoreHobLib/HobLib.c

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