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