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