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