MdePkg/Library/DxeHobLib/HobLib.c

   1 /** @file
   2   HOB Library.
   3
   4   Copyright (c) 2006 - 2007, Intel Corporation<BR>
   5   All rights reserved. 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
  16 //
  17 // The package level header files this module uses
  18 //
  19 #include <PiDxe.h>
  20 //
  21 // The protocols, PPI and GUID defintions for this module
  22 //
  23 #include <Guid/HobList.h>
  24 //
  25 // The Library classes this module consumes
  26 //
  27 #include <Library/HobLib.h>
  28 #include <Library/UefiLib.h>
  29 #include <Library/DebugLib.h>
  30 #include <Library/BaseMemoryLib.h>
  31 #include "HobLibInternal.h"
  32
  33 STATIC VOID  *mHobList = NULL;
  34
  35 /**
  36   The constructor function caches the pointer to HOB list.
  37
  38   The constructor function gets the start address of HOB list from system configuration table.
  39   It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
  40
  41   @param  ImageHandle   The firmware allocated handle for the EFI image.
  42   @param  SystemTable   A pointer to the EFI System Table.
  43
  44   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  45
  46 **/
  47 EFI_STATUS
  48 EFIAPI
  49 HobLibConstructor (
  50   IN EFI_HANDLE        ImageHandle,
  51   IN EFI_SYSTEM_TABLE  *SystemTable
  52   )
  53 {
  54   EFI_STATUS  Status;
  55
  56   Status = EfiGetSystemConfigurationTable (&gEfiHobListGuid, &mHobList);
  57   ASSERT_EFI_ERROR (Status);
  58   ASSERT (mHobList != NULL);
  59   return Status;
  60 }
  61
  62 /**
  63   Returns the pointer to the HOB list.
  64
  65   This function returns the pointer to first HOB in the list.
  66
  67   @return The pointer to the HOB list.
  68
  69 **/
  70 VOID *
  71 EFIAPI
  72 GetHobList (
  73   VOID
  74   )
  75 {
  76   return mHobList;
  77 }
  78
  79 /**
  80   Returns the next instance of a HOB type from the starting HOB.
  81
  82   This function searches the first instance of a HOB type from the starting HOB pointer.
  83   If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  84   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  85   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  86   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  87   If HobStart is NULL, then ASSERT().
  88
  89   @param  Type          The HOB type to return.
  90   @param  HobStart      The starting HOB pointer to search from.
  91
  92   @return The next instance of a HOB type from the starting HOB.
  93
  94 **/
  95 VOID *
  96 EFIAPI
  97 GetNextHob (
  98   IN UINT16                 Type,
  99   IN CONST VOID             *HobStart
 100   )
 101 {
 102   EFI_PEI_HOB_POINTERS  Hob;
 103
 104   ASSERT (HobStart != NULL);
 105
 106   Hob.Raw = (UINT8 *) HobStart;
 107   //
 108   // Parse the HOB list until end of list or matching type is found.
 109   //
 110   while (!END_OF_HOB_LIST (Hob)) {
 111     if (Hob.Header->HobType == Type) {
 112       return Hob.Raw;
 113     }
 114     Hob.Raw = GET_NEXT_HOB (Hob);
 115   }
 116   return NULL;
 117 }
 118
 119 /**
 120   Returns the first instance of a HOB type among the whole HOB list.
 121
 122   This function searches the first instance of a HOB type among the whole HOB list.
 123   If there does not exist such HOB type in the HOB list, it will return NULL.
 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   This function searches the first instance of a HOB from the starting HOB pointer.
 144   Such HOB should satisfy two conditions:
 145   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 146   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 147   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 148   to extract the data section and its size info respectively.
 149   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
 150   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
 151   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
 152   If Guid is NULL, then ASSERT().
 153   If HobStart is NULL, then ASSERT().
 154
 155   @param  Guid          The GUID to match with in the HOB list.
 156   @param  HobStart      A pointer to a Guid.
 157
 158   @return The next instance of the matched GUID HOB from the starting HOB.
 159
 160 **/
 161 VOID *
 162 EFIAPI
 163 GetNextGuidHob (
 164   IN CONST EFI_GUID         *Guid,
 165   IN CONST VOID             *HobStart
 166   )
 167 {
 168   EFI_PEI_HOB_POINTERS  GuidHob;
 169
 170   GuidHob.Raw = (UINT8 *) HobStart;
 171   while ((GuidHob.Raw = GetNextHob (EFI_HOB_TYPE_GUID_EXTENSION, GuidHob.Raw)) != NULL) {
 172     if (CompareGuid (Guid, &GuidHob.Guid->Name)) {
 173       break;
 174     }
 175     GuidHob.Raw = GET_NEXT_HOB (GuidHob);
 176   }
 177   return GuidHob.Raw;
 178 }
 179
 180 /**
 181   This function searches the first instance of a HOB among the whole HOB list.
 182   Such HOB should satisfy two conditions:
 183   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 184   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 185   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 186   to extract the data section and its size info respectively.
 187   If Guid is NULL, then ASSERT().
 188
 189   @param  Guid          The GUID to match with in the HOB list.
 190
 191   @return The first instance of the matched GUID HOB among the whole HOB list.
 192
 193 **/
 194 VOID *
 195 EFIAPI
 196 GetFirstGuidHob (
 197   IN CONST EFI_GUID         *Guid
 198   )
 199 {
 200   VOID      *HobList;
 201
 202   HobList = GetHobList ();
 203   return GetNextGuidHob (Guid, HobList);
 204 }
 205
 206 /**
 207   Get the Boot Mode from the HOB list.
 208
 209   This function returns the system boot mode information from the
 210   PHIT HOB in HOB list.
 211
 212   @param  VOID
 213
 214   @return The Boot Mode.
 215
 216 **/
 217 EFI_BOOT_MODE
 218 EFIAPI
 219 GetBootModeHob (
 220   VOID
 221   )
 222 {
 223   EFI_HOB_HANDOFF_INFO_TABLE    *HandOffHob;
 224
 225   HandOffHob = (EFI_HOB_HANDOFF_INFO_TABLE *) GetHobList ();
 226
 227   return  HandOffHob->BootMode;
 228 }
 229
 230 /**
 231   Builds a HOB for a loaded PE32 module.
 232
 233   This function builds a HOB for a loaded PE32 module.
 234   It can only be invoked during PEI phase;
 235   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 236   If ModuleName is NULL, then ASSERT().
 237   If there is no additional space for HOB creation, then ASSERT().
 238
 239   @param  ModuleName              The GUID File Name of the module.
 240   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 241   @param  ModuleLength            The length of the module in bytes.
 242   @param  EntryPoint              The 64 bit physical address of the module's entry point.
 243
 244 **/
 245 VOID
 246 EFIAPI
 247 BuildModuleHob (
 248   IN CONST EFI_GUID         *ModuleName,
 249   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 250   IN UINT64                 ModuleLength,
 251   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 252   )
 253 {
 254   //
 255   // PEI HOB is read only for DXE phase
 256   //
 257   ASSERT (FALSE);
 258 }
 259
 260 /**
 261   Builds a HOB that describes a chunk of system memory.
 262
 263   This function builds a HOB that describes a chunk of system memory.
 264   It can only be invoked during PEI phase;
 265   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 266   If there is no additional space for HOB creation, then ASSERT().
 267
 268   @param  ResourceType        The type of resource described by this HOB.
 269   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 270   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 271   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 272
 273 **/
 274 VOID
 275 EFIAPI
 276 BuildResourceDescriptorHob (
 277   IN EFI_RESOURCE_TYPE            ResourceType,
 278   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 279   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 280   IN UINT64                       NumberOfBytes
 281   )
 282 {
 283   //
 284   // PEI HOB is read only for DXE phase
 285   //
 286   ASSERT (FALSE);
 287 }
 288
 289 /**
 290   Builds a GUID HOB with a certain data length.
 291
 292   This function builds a customized HOB tagged with a GUID for identification
 293   and returns the start address of GUID HOB data so that caller can fill the customized data.
 294   The HOB Header and Name field is already stripped.
 295   It can only be invoked during PEI phase;
 296   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 297   If Guid is NULL, then ASSERT().
 298   If there is no additional space for HOB creation, then ASSERT().
 299   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 300
 301   @param  Guid          The GUID to tag the customized HOB.
 302   @param  DataLength    The size of the data payload for the GUID HOB.
 303
 304   @return The start address of GUID HOB data.
 305
 306 **/
 307 VOID *
 308 EFIAPI
 309 BuildGuidHob (
 310   IN CONST EFI_GUID              *Guid,
 311   IN UINTN                       DataLength
 312   )
 313 {
 314   //
 315   // PEI HOB is read only for DXE phase
 316   //
 317   ASSERT (FALSE);
 318   return NULL;
 319 }
 320
 321 /**
 322   Copies a data buffer to a newly-built HOB.
 323
 324   This function builds a customized HOB tagged with a GUID for identification,
 325   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 326   The HOB Header and Name field is already stripped.
 327   It can only be invoked during PEI phase;
 328   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 329   If Guid is NULL, then ASSERT().
 330   If Data is NULL and DataLength > 0, then ASSERT().
 331   If there is no additional space for HOB creation, then ASSERT().
 332   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 333
 334   @param  Guid          The GUID to tag the customized HOB.
 335   @param  Data          The data to be copied into the data field of the GUID HOB.
 336   @param  DataLength    The size of the data payload for the GUID HOB.
 337
 338   @return The start address of GUID HOB data.
 339
 340 **/
 341 VOID *
 342 EFIAPI
 343 BuildGuidDataHob (
 344   IN CONST EFI_GUID              *Guid,
 345   IN VOID                        *Data,
 346   IN UINTN                       DataLength
 347   )
 348 {
 349   //
 350   // PEI HOB is read only for DXE phase
 351   //
 352   ASSERT (FALSE);
 353   return NULL;
 354 }
 355
 356 /**
 357   Builds a Firmware Volume HOB.
 358
 359   This function builds a Firmware Volume HOB.
 360   It can only be invoked during PEI phase;
 361   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 362   If there is no additional space for HOB creation, then ASSERT().
 363
 364   @param  BaseAddress   The base address of the Firmware Volume.
 365   @param  Length        The size of the Firmware Volume in bytes.
 366
 367 **/
 368 VOID
 369 EFIAPI
 370 BuildFvHob (
 371   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 372   IN UINT64                      Length
 373   )
 374 {
 375   //
 376   // PEI HOB is read only for DXE phase
 377   //
 378   ASSERT (FALSE);
 379 }
 380
 381 /**
 382   Builds a Capsule Volume HOB.
 383
 384   This function builds a Capsule Volume HOB.
 385   It can only be invoked during PEI phase;
 386   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 387   If there is no additional space for HOB creation, then ASSERT().
 388
 389   @param  BaseAddress   The base address of the Capsule Volume.
 390   @param  Length        The size of the Capsule Volume in bytes.
 391
 392 **/
 393 VOID
 394 EFIAPI
 395 BuildCvHob (
 396   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 397   IN UINT64                      Length
 398   )
 399 {
 400   //
 401   // PEI HOB is read only for DXE phase
 402   //
 403   ASSERT (FALSE);
 404 }
 405
 406 /**
 407   Builds a HOB for the CPU.
 408
 409   This function builds a HOB for the CPU.
 410   It can only be invoked during PEI phase;
 411   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 412   If there is no additional space for HOB creation, then ASSERT().
 413
 414   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 415   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 416
 417 **/
 418 VOID
 419 EFIAPI
 420 BuildCpuHob (
 421   IN UINT8                       SizeOfMemorySpace,
 422   IN UINT8                       SizeOfIoSpace
 423   )
 424 {
 425   //
 426   // PEI HOB is read only for DXE phase
 427   //
 428   ASSERT (FALSE);
 429 }
 430
 431 /**
 432   Builds a HOB for the Stack.
 433
 434   This function builds a HOB for the stack.
 435   It can only be invoked during PEI phase;
 436   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 437   If there is no additional space for HOB creation, then ASSERT().
 438
 439   @param  BaseAddress   The 64 bit physical address of the Stack.
 440   @param  Length        The length of the stack in bytes.
 441
 442 **/
 443 VOID
 444 EFIAPI
 445 BuildStackHob (
 446   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 447   IN UINT64                      Length
 448   )
 449 {
 450   //
 451   // PEI HOB is read only for DXE phase
 452   //
 453   ASSERT (FALSE);
 454 }
 455
 456 /**
 457   Builds a HOB for the BSP store.
 458
 459   This function builds a HOB for BSP store.
 460   It can only be invoked during PEI phase;
 461   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 462   If there is no additional space for HOB creation, then ASSERT().
 463
 464   @param  BaseAddress   The 64 bit physical address of the BSP.
 465   @param  Length        The length of the BSP store in bytes.
 466   @param  MemoryType    Type of memory allocated by this HOB.
 467
 468 **/
 469 VOID
 470 EFIAPI
 471 BuildBspStoreHob (
 472   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 473   IN UINT64                      Length,
 474   IN EFI_MEMORY_TYPE             MemoryType
 475   )
 476 {
 477   //
 478   // PEI HOB is read only for DXE phase
 479   //
 480   ASSERT (FALSE);
 481 }
 482
 483 /**
 484   Builds a HOB for the memory allocation.
 485
 486   This function builds a HOB for the memory allocation.
 487   It can only be invoked during PEI phase;
 488   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 489   If there is no additional space for HOB creation, then ASSERT().
 490
 491   @param  BaseAddress   The 64 bit physical address of the memory.
 492   @param  Length        The length of the memory allocation in bytes.
 493   @param  MemoryType    Type of memory allocated by this HOB.
 494
 495 **/
 496 VOID
 497 EFIAPI
 498 BuildMemoryAllocationHob (
 499   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 500   IN UINT64                      Length,
 501   IN EFI_MEMORY_TYPE             MemoryType
 502   )
 503 {
 504   //
 505   // PEI HOB is read only for DXE phase
 506   //
 507   ASSERT (FALSE);
 508 }