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