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