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