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