MdePkg/Library/DxeHobLib/HobLib.c

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