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