MdePkg/Library/DxeHobLib/HobLib.c

   1 /** @file
   2   HOB Library implemenation for Dxe Phase.
   3
   4   Copyright (c) 2006 - 2008, 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
  26 STATIC VOID  *mHobList = NULL;
  27
  28 /**
  29   The constructor function caches the pointer to HOB list.
  30
  31   The constructor function gets the start address of HOB list from system configuration table.
  32   It will ASSERT() if that operation fails and it will always return EFI_SUCCESS.
  33
  34   @param  ImageHandle   The firmware allocated handle for the EFI image.
  35   @param  SystemTable   A pointer to the EFI System Table.
  36
  37   @retval EFI_SUCCESS   The constructor always returns EFI_SUCCESS.
  38
  39 **/
  40 EFI_STATUS
  41 EFIAPI
  42 HobLibConstructor (
  43   IN EFI_HANDLE        ImageHandle,
  44   IN EFI_SYSTEM_TABLE  *SystemTable
  45   )
  46 {
  47   EFI_STATUS  Status;
  48
  49         Status = EfiGetSystemConfigurationTable (&gEfiHobListGuid, &mHobList);
  50   ASSERT_EFI_ERROR (Status);
  51   ASSERT (mHobList != NULL);
  52
  53   return EFI_SUCCESS;
  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. If PHIT HOB is NULL, then ASSERT().
 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   ASSERT (HandOffHob != NULL);
 221
 222   return  HandOffHob->BootMode;
 223 }
 224
 225 /**
 226   Builds a HOB for a loaded PE32 module.
 227
 228   This function builds a HOB for a loaded PE32 module.
 229   It can only be invoked during PEI phase;
 230   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 231   If ModuleName is NULL, then ASSERT().
 232   If there is no additional space for HOB creation, then ASSERT().
 233
 234   @param  ModuleName              The GUID File Name of the module.
 235   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 236   @param  ModuleLength            The length of the module in bytes.
 237   @param  EntryPoint              The 64 bit physical address of the module's entry point.
 238
 239 **/
 240 VOID
 241 EFIAPI
 242 BuildModuleHob (
 243   IN CONST EFI_GUID         *ModuleName,
 244   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 245   IN UINT64                 ModuleLength,
 246   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 247   )
 248 {
 249   //
 250   // PEI HOB is read only for DXE phase
 251   //
 252   ASSERT (FALSE);
 253 }
 254
 255 /**
 256   Builds a HOB that describes a chunk of system memory.
 257
 258   This function builds a HOB that describes a chunk of system memory.
 259   It can only be invoked during PEI phase;
 260   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 261   If there is no additional space for HOB creation, then ASSERT().
 262
 263   @param  ResourceType        The type of resource described by this HOB.
 264   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 265   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 266   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 267
 268 **/
 269 VOID
 270 EFIAPI
 271 BuildResourceDescriptorHob (
 272   IN EFI_RESOURCE_TYPE            ResourceType,
 273   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 274   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 275   IN UINT64                       NumberOfBytes
 276   )
 277 {
 278   //
 279   // PEI HOB is read only for DXE phase
 280   //
 281   ASSERT (FALSE);
 282 }
 283
 284 /**
 285   Builds a GUID HOB with a certain data length.
 286
 287   This function builds a customized HOB tagged with a GUID for identification
 288   and returns the start address of GUID HOB data so that caller can fill the customized data.
 289   The HOB Header and Name field is already stripped.
 290   It can only be invoked during PEI phase;
 291   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 292   If Guid is NULL, then ASSERT().
 293   If there is no additional space for HOB creation, then ASSERT().
 294   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 295
 296   @param  Guid          The GUID to tag the customized HOB.
 297   @param  DataLength    The size of the data payload for the GUID HOB.
 298
 299   @return The start address of GUID HOB data.
 300
 301 **/
 302 VOID *
 303 EFIAPI
 304 BuildGuidHob (
 305   IN CONST EFI_GUID              *Guid,
 306   IN UINTN                       DataLength
 307   )
 308 {
 309   //
 310   // PEI HOB is read only for DXE phase
 311   //
 312   ASSERT (FALSE);
 313   return NULL;
 314 }
 315
 316 /**
 317   Copies a data buffer to a newly-built HOB.
 318
 319   This function builds a customized HOB tagged with a GUID for identification,
 320   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 321   The HOB Header and Name field is already stripped.
 322   It can only be invoked during PEI phase;
 323   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 324   If Guid is NULL, then ASSERT().
 325   If Data is NULL and DataLength > 0, then ASSERT().
 326   If there is no additional space for HOB creation, then ASSERT().
 327   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 328
 329   @param  Guid          The GUID to tag the customized HOB.
 330   @param  Data          The data to be copied into the data field of the GUID HOB.
 331   @param  DataLength    The size of the data payload for the GUID HOB.
 332
 333   @return The start address of GUID HOB data.
 334
 335 **/
 336 VOID *
 337 EFIAPI
 338 BuildGuidDataHob (
 339   IN CONST EFI_GUID              *Guid,
 340   IN VOID                        *Data,
 341   IN UINTN                       DataLength
 342   )
 343 {
 344   //
 345   // PEI HOB is read only for DXE phase
 346   //
 347   ASSERT (FALSE);
 348   return NULL;
 349 }
 350
 351 /**
 352   Builds a Firmware Volume HOB.
 353
 354   This function builds a Firmware Volume HOB.
 355   It can only be invoked during PEI phase;
 356   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 357   If there is no additional space for HOB creation, then ASSERT().
 358
 359   @param  BaseAddress   The base address of the Firmware Volume.
 360   @param  Length        The size of the Firmware Volume in bytes.
 361
 362 **/
 363 VOID
 364 EFIAPI
 365 BuildFvHob (
 366   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 367   IN UINT64                      Length
 368   )
 369 {
 370   //
 371   // PEI HOB is read only for DXE phase
 372   //
 373   ASSERT (FALSE);
 374 }
 375
 376 /**
 377   Builds a EFI_HOB_TYPE_FV2 HOB.
 378
 379   This function builds a EFI_HOB_TYPE_FV2 HOB.
 380   It can only be invoked during PEI phase;
 381   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 382   If there is no additional space for HOB creation, then ASSERT().
 383
 384   @param  BaseAddress   The base address of the Firmware Volume.
 385   @param  Length        The size of the Firmware Volume in bytes.
 386   @param  FvName       The name of the Firmware Volume.
 387   @param  FileName      The name of the file.
 388
 389 **/
 390 VOID
 391 EFIAPI
 392 BuildFv2Hob (
 393   IN          EFI_PHYSICAL_ADDRESS        BaseAddress,
 394   IN          UINT64                      Length,
 395   IN CONST    EFI_GUID                    *FvName,
 396   IN CONST    EFI_GUID                    *FileName
 397   )
 398 {
 399   ASSERT (FALSE);
 400 }
 401
 402
 403 /**
 404   Builds a Capsule Volume HOB.
 405
 406   This function builds a Capsule Volume HOB.
 407   It can only be invoked during PEI phase;
 408   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 409   If there is no additional space for HOB creation, then ASSERT().
 410
 411   @param  BaseAddress   The base address of the Capsule Volume.
 412   @param  Length        The size of the Capsule Volume in bytes.
 413
 414 **/
 415 VOID
 416 EFIAPI
 417 BuildCvHob (
 418   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 419   IN UINT64                      Length
 420   )
 421 {
 422   //
 423   // PEI HOB is read only for DXE phase
 424   //
 425   ASSERT (FALSE);
 426 }
 427
 428 /**
 429   Builds a HOB for the CPU.
 430
 431   This function builds a HOB for the CPU.
 432   It can only be invoked during PEI phase;
 433   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 434   If there is no additional space for HOB creation, then ASSERT().
 435
 436   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 437   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 438
 439 **/
 440 VOID
 441 EFIAPI
 442 BuildCpuHob (
 443   IN UINT8                       SizeOfMemorySpace,
 444   IN UINT8                       SizeOfIoSpace
 445   )
 446 {
 447   //
 448   // PEI HOB is read only for DXE phase
 449   //
 450   ASSERT (FALSE);
 451 }
 452
 453 /**
 454   Builds a HOB for the Stack.
 455
 456   This function builds a HOB for the stack.
 457   It can only be invoked during PEI phase;
 458   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 459   If there is no additional space for HOB creation, then ASSERT().
 460
 461   @param  BaseAddress   The 64 bit physical address of the Stack.
 462   @param  Length        The length of the stack in bytes.
 463
 464 **/
 465 VOID
 466 EFIAPI
 467 BuildStackHob (
 468   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 469   IN UINT64                      Length
 470   )
 471 {
 472   //
 473   // PEI HOB is read only for DXE phase
 474   //
 475   ASSERT (FALSE);
 476 }
 477
 478 /**
 479   Builds a HOB for the BSP store.
 480
 481   This function builds a HOB for BSP store.
 482   It can only be invoked during PEI phase;
 483   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 484   If there is no additional space for HOB creation, then ASSERT().
 485
 486   @param  BaseAddress   The 64 bit physical address of the BSP.
 487   @param  Length        The length of the BSP store in bytes.
 488   @param  MemoryType    Type of memory allocated by this HOB.
 489
 490 **/
 491 VOID
 492 EFIAPI
 493 BuildBspStoreHob (
 494   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 495   IN UINT64                      Length,
 496   IN EFI_MEMORY_TYPE             MemoryType
 497   )
 498 {
 499   //
 500   // PEI HOB is read only for DXE phase
 501   //
 502   ASSERT (FALSE);
 503 }
 504
 505 /**
 506   Builds a HOB for the memory allocation.
 507
 508   This function builds a HOB for the memory allocation.
 509   It can only be invoked during PEI phase;
 510   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 511   If there is no additional space for HOB creation, then ASSERT().
 512
 513   @param  BaseAddress   The 64 bit physical address of the memory.
 514   @param  Length        The length of the memory allocation in bytes.
 515   @param  MemoryType    Type of memory allocated by this HOB.
 516
 517 **/
 518 VOID
 519 EFIAPI
 520 BuildMemoryAllocationHob (
 521   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 522   IN UINT64                      Length,
 523   IN EFI_MEMORY_TYPE             MemoryType
 524   )
 525 {
 526   //
 527   // PEI HOB is read only for DXE phase
 528   //
 529   ASSERT (FALSE);
 530 }