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