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