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