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