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