MdePkg/Library/DxeCoreHobLib/HobLib.c

   1 /** @file
   2   HOB Library.
   3
   4   Copyright (c) 2006, 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   Builds a HOB for a loaded PE32 module.
 165
 166   This function builds a HOB for a loaded PE32 module.
 167   It can only be invoked during PEI phase;
 168   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 169   If ModuleName is NULL, then ASSERT().
 170   If there is no additional space for HOB creation, then ASSERT().
 171
 172   @param  ModuleName              The GUID File Name of the module.
 173   @param  MemoryAllocationModule  The 64 bit physical address of the module.
 174   @param  ModuleLength            The length of the module in bytes.
 175   @param  EntryPoint              The 64 bit physical address of the module's entry point.
 176
 177 **/
 178 VOID
 179 EFIAPI
 180 BuildModuleHob (
 181   IN CONST EFI_GUID         *ModuleName,
 182   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 183   IN UINT64                 ModuleLength,
 184   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 185   )
 186 {
 187   //
 188   // PEI HOB is read only for DXE phase
 189   //
 190   ASSERT (FALSE);
 191 }
 192
 193 /**
 194   Builds a HOB that describes a chunk of system memory.
 195
 196   This function builds a HOB that describes a chunk of system memory.
 197   It can only be invoked during PEI phase;
 198   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 199   If there is no additional space for HOB creation, then ASSERT().
 200
 201   @param  ResourceType        The type of resource described by this HOB.
 202   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 203   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 204   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 205
 206 **/
 207 VOID
 208 EFIAPI
 209 BuildResourceDescriptorHob (
 210   IN EFI_RESOURCE_TYPE            ResourceType,
 211   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 212   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 213   IN UINT64                       NumberOfBytes
 214   )
 215 {
 216   //
 217   // PEI HOB is read only for DXE phase
 218   //
 219   ASSERT (FALSE);
 220 }
 221
 222 /**
 223   Builds a GUID HOB with a certain data length.
 224
 225   This function builds a customized HOB tagged with a GUID for identification
 226   and returns the start address of GUID HOB data so that caller can fill the customized data.
 227   The HOB Header and Name field is already stripped.
 228   It can only be invoked during PEI phase;
 229   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 230   If Guid is NULL, then ASSERT().
 231   If there is no additional space for HOB creation, then ASSERT().
 232   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 233
 234   @param  Guid          The GUID to tag the customized HOB.
 235   @param  DataLength    The size of the data payload for the GUID HOB.
 236
 237   @return The start address of GUID HOB data.
 238
 239 **/
 240 VOID *
 241 EFIAPI
 242 BuildGuidHob (
 243   IN CONST EFI_GUID              *Guid,
 244   IN UINTN                       DataLength
 245   )
 246 {
 247   //
 248   // PEI HOB is read only for DXE phase
 249   //
 250   ASSERT (FALSE);
 251   return NULL;
 252 }
 253
 254 /**
 255   Copies a data buffer to a newly-built HOB.
 256
 257   This function builds a customized HOB tagged with a GUID for identification,
 258   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 259   The HOB Header and Name field is already stripped.
 260   It can only be invoked during PEI phase;
 261   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 262   If Guid is NULL, then ASSERT().
 263   If Data is NULL and DataLength > 0, then ASSERT().
 264   If there is no additional space for HOB creation, then ASSERT().
 265   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 266
 267   @param  Guid          The GUID to tag the customized HOB.
 268   @param  Data          The data to be copied into the data field of the GUID HOB.
 269   @param  DataLength    The size of the data payload for the GUID HOB.
 270
 271   @return The start address of GUID HOB data.
 272
 273 **/
 274 VOID *
 275 EFIAPI
 276 BuildGuidDataHob (
 277   IN CONST EFI_GUID              *Guid,
 278   IN VOID                        *Data,
 279   IN UINTN                       DataLength
 280   )
 281 {
 282   //
 283   // PEI HOB is read only for DXE phase
 284   //
 285   ASSERT (FALSE);
 286   return NULL;
 287 }
 288
 289 /**
 290   Builds a Firmware Volume HOB.
 291
 292   This function builds a Firmware Volume HOB.
 293   It can only be invoked during PEI phase;
 294   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 295   If there is no additional space for HOB creation, then ASSERT().
 296
 297   @param  BaseAddress   The base address of the Firmware Volume.
 298   @param  Length        The size of the Firmware Volume in bytes.
 299
 300 **/
 301 VOID
 302 EFIAPI
 303 BuildFvHob (
 304   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 305   IN UINT64                      Length
 306   )
 307 {
 308   //
 309   // PEI HOB is read only for DXE phase
 310   //
 311   ASSERT (FALSE);
 312 }
 313
 314 /**
 315   Builds a Capsule Volume HOB.
 316
 317   This function builds a Capsule Volume HOB.
 318   It can only be invoked during PEI phase;
 319   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 320   If there is no additional space for HOB creation, then ASSERT().
 321
 322   @param  BaseAddress   The base address of the Capsule Volume.
 323   @param  Length        The size of the Capsule Volume in bytes.
 324
 325 **/
 326 VOID
 327 EFIAPI
 328 BuildCvHob (
 329   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 330   IN UINT64                      Length
 331   )
 332 {
 333   //
 334   // PEI HOB is read only for DXE phase
 335   //
 336   ASSERT (FALSE);
 337 }
 338
 339 /**
 340   Builds a HOB for the CPU.
 341
 342   This function builds a HOB for the CPU.
 343   It can only be invoked during PEI phase;
 344   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 345   If there is no additional space for HOB creation, then ASSERT().
 346
 347   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 348   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 349
 350 **/
 351 VOID
 352 EFIAPI
 353 BuildCpuHob (
 354   IN UINT8                       SizeOfMemorySpace,
 355   IN UINT8                       SizeOfIoSpace
 356   )
 357 {
 358   //
 359   // PEI HOB is read only for DXE phase
 360   //
 361   ASSERT (FALSE);
 362 }
 363
 364 /**
 365   Builds a HOB for the Stack.
 366
 367   This function builds a HOB for the stack.
 368   It can only be invoked during PEI phase;
 369   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 370   If there is no additional space for HOB creation, then ASSERT().
 371
 372   @param  BaseAddress   The 64 bit physical address of the Stack.
 373   @param  Length        The length of the stack in bytes.
 374
 375 **/
 376 VOID
 377 EFIAPI
 378 BuildStackHob (
 379   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 380   IN UINT64                      Length
 381   )
 382 {
 383   //
 384   // PEI HOB is read only for DXE phase
 385   //
 386   ASSERT (FALSE);
 387 }
 388
 389 /**
 390   Builds a HOB for the BSP store.
 391
 392   This function builds a HOB for BSP store.
 393   It can only be invoked during PEI phase;
 394   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 395   If there is no additional space for HOB creation, then ASSERT().
 396
 397   @param  BaseAddress   The 64 bit physical address of the BSP.
 398   @param  Length        The length of the BSP store in bytes.
 399   @param  MemoryType    Type of memory allocated by this HOB.
 400
 401 **/
 402 VOID
 403 EFIAPI
 404 BuildBspStoreHob (
 405   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 406   IN UINT64                      Length,
 407   IN EFI_MEMORY_TYPE             MemoryType
 408   )
 409 {
 410   //
 411   // PEI HOB is read only for DXE phase
 412   //
 413   ASSERT (FALSE);
 414 }
 415
 416 /**
 417   Builds a HOB for the memory allocation.
 418
 419   This function builds a HOB for the memory allocation.
 420   It can only be invoked during PEI phase;
 421   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 422   If there is no additional space for HOB creation, then ASSERT().
 423
 424   @param  BaseAddress   The 64 bit physical address of the memory.
 425   @param  Length        The length of the memory allocation in bytes.
 426   @param  MemoryType    Type of memory allocated by this HOB.
 427
 428 **/
 429 VOID
 430 EFIAPI
 431 BuildMemoryAllocationHob (
 432   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 433   IN UINT64                      Length,
 434   IN EFI_MEMORY_TYPE             MemoryType
 435   )
 436 {
 437   //
 438   // PEI HOB is read only for DXE phase
 439   //
 440   ASSERT (FALSE);
 441 }