MdePkg/Library/PeiHobLib/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 **/
  14
  15
  16 #include <PiPei.h>
  17
  18 #include <Guid/MemoryAllocationHob.h>
  19
  20 #include <Library/HobLib.h>
  21 #include <Library/DebugLib.h>
  22 #include <Library/PeiServicesLib.h>
  23 #include <Library/BaseMemoryLib.h>
  24
  25 /**
  26   Returns the pointer to the HOB list.
  27
  28   This function returns the pointer to first HOB in the list.
  29
  30   @return The pointer to the HOB list.
  31
  32 **/
  33 VOID *
  34 EFIAPI
  35 GetHobList (
  36   VOID
  37   )
  38 {
  39   EFI_STATUS            Status;
  40   VOID                  *HobList;
  41
  42   Status = PeiServicesGetHobList (&HobList);
  43   ASSERT_EFI_ERROR (Status);
  44   ASSERT (HobList != NULL);
  45
  46   return HobList;
  47 }
  48
  49 /**
  50   Returns the next instance of a HOB type from the starting HOB.
  51
  52   This function searches the first instance of a HOB type from the starting HOB pointer.
  53   If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  54   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
  55   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
  56   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
  57   If HobStart is NULL, then ASSERT().
  58
  59   @param  Type          The HOB type to return.
  60   @param  HobStart      The starting HOB pointer to search from.
  61
  62   @return The next instance of a HOB type from the starting HOB.
  63
  64 **/
  65 VOID *
  66 EFIAPI
  67 GetNextHob (
  68   IN UINT16                 Type,
  69   IN CONST VOID             *HobStart
  70   )
  71 {
  72   EFI_PEI_HOB_POINTERS  Hob;
  73
  74   ASSERT (HobStart != NULL);
  75
  76   Hob.Raw = (UINT8 *) HobStart;
  77   //
  78   // Parse the HOB list until end of list or matching type is found.
  79   //
  80   while (!END_OF_HOB_LIST (Hob)) {
  81     if (Hob.Header->HobType == Type) {
  82       return Hob.Raw;
  83     }
  84     Hob.Raw = GET_NEXT_HOB (Hob);
  85   }
  86   return NULL;
  87 }
  88
  89 /**
  90   Returns the first instance of a HOB type among the whole HOB list.
  91
  92   This function searches the first instance of a HOB type among the whole HOB list.
  93   If there does not exist such HOB type in the HOB list, it will return NULL.
  94
  95   @param  Type          The HOB type to return.
  96
  97   @return The next instance of a HOB type from the starting HOB.
  98
  99 **/
 100 VOID *
 101 EFIAPI
 102 GetFirstHob (
 103   IN UINT16                 Type
 104   )
 105 {
 106   VOID      *HobList;
 107
 108   HobList = GetHobList ();
 109   return GetNextHob (Type, HobList);
 110 }
 111
 112 /**
 113   This function searches the first instance of a HOB from the starting HOB pointer.
 114   Such HOB should satisfy two conditions:
 115   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 116   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 117   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 118   to extract the data section and its size info respectively.
 119   In contrast with macro GET_NEXT_HOB(), this function does not skip the starting HOB pointer
 120   unconditionally: it returns HobStart back if HobStart itself meets the requirement;
 121   caller is required to use GET_NEXT_HOB() if it wishes to skip current HobStart.
 122   If Guid is NULL, then ASSERT().
 123   If HobStart is NULL, then ASSERT().
 124
 125   @param  Guid          The GUID to match with in the HOB list.
 126   @param  HobStart      A pointer to a Guid.
 127
 128   @return The next instance of the matched GUID HOB from the starting HOB.
 129
 130 **/
 131 VOID *
 132 EFIAPI
 133 GetNextGuidHob (
 134   IN CONST EFI_GUID         *Guid,
 135   IN CONST VOID             *HobStart
 136   )
 137 {
 138   EFI_PEI_HOB_POINTERS  GuidHob;
 139
 140   GuidHob.Raw = (UINT8 *) HobStart;
 141   while ((GuidHob.Raw = GetNextHob (EFI_HOB_TYPE_GUID_EXTENSION, GuidHob.Raw)) != NULL) {
 142     if (CompareGuid (Guid, &GuidHob.Guid->Name)) {
 143       break;
 144     }
 145     GuidHob.Raw = GET_NEXT_HOB (GuidHob);
 146   }
 147   return GuidHob.Raw;
 148 }
 149
 150 /**
 151   This function searches the first instance of a HOB among the whole HOB list.
 152   Such HOB should satisfy two conditions:
 153   its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
 154   If there does not exist such HOB from the starting HOB pointer, it will return NULL.
 155   Caller is required to apply GET_GUID_HOB_DATA () and GET_GUID_HOB_DATA_SIZE ()
 156   to extract the data section and its size info respectively.
 157   If Guid is NULL, then ASSERT().
 158
 159   @param  Guid          The GUID to match with in the HOB list.
 160
 161   @return The first instance of the matched GUID HOB among the whole HOB list.
 162
 163 **/
 164 VOID *
 165 EFIAPI
 166 GetFirstGuidHob (
 167   IN CONST EFI_GUID         *Guid
 168   )
 169 {
 170   VOID      *HobList;
 171
 172   HobList = GetHobList ();
 173   return GetNextGuidHob (Guid, HobList);
 174 }
 175
 176 /**
 177   Get the Boot Mode from the HOB list.
 178
 179   This function returns the system boot mode information from the
 180   PHIT HOB in HOB list.
 181
 182   @param  VOID
 183
 184   @return The Boot Mode.
 185
 186 **/
 187 EFI_BOOT_MODE
 188 EFIAPI
 189 GetBootModeHob (
 190   VOID
 191   )
 192 {
 193   EFI_STATUS             Status;
 194   EFI_BOOT_MODE          BootMode;
 195
 196   Status = PeiServicesGetBootMode (&BootMode);
 197   ASSERT_EFI_ERROR (Status);
 198
 199   return BootMode;
 200 }
 201
 202 /**
 203   Adds a new HOB to the HOB List.
 204
 205   This internal function enables PEIMs to create various types of HOBs.
 206
 207   @param  Type          Type of the new HOB.
 208   @param  Length        Length of the new HOB to allocate.
 209
 210   @return The address of new HOB.
 211
 212 **/
 213 STATIC
 214 VOID *
 215 InternalPeiCreateHob (
 216   IN UINT16                      Type,
 217   IN UINT16                      Length
 218   )
 219 {
 220   EFI_STATUS        Status;
 221   VOID              *Hob;
 222
 223   Status = PeiServicesCreateHob (Type, Length, &Hob);
 224   //
 225   // Assume the process of HOB building is always successful.
 226   //
 227   ASSERT_EFI_ERROR (Status);
 228   return Hob;
 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   EFI_HOB_MEMORY_ALLOCATION_MODULE  *Hob;
 256
 257   ASSERT (((MemoryAllocationModule & (EFI_PAGE_SIZE - 1)) == 0) &&
 258           ((ModuleLength & (EFI_PAGE_SIZE - 1)) == 0));
 259
 260   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_MODULE));
 261
 262   CopyGuid (&(Hob->MemoryAllocationHeader.Name), &gEfiHobMemoryAllocModuleGuid);
 263   Hob->MemoryAllocationHeader.MemoryBaseAddress = MemoryAllocationModule;
 264   Hob->MemoryAllocationHeader.MemoryLength      = ModuleLength;
 265   Hob->MemoryAllocationHeader.MemoryType        = EfiBootServicesCode;
 266
 267   //
 268   // Zero the reserved space to match HOB spec
 269   //
 270   ZeroMem (Hob->MemoryAllocationHeader.Reserved, sizeof (Hob->MemoryAllocationHeader.Reserved));
 271
 272   CopyGuid (&Hob->ModuleName, ModuleName);
 273   Hob->EntryPoint = EntryPoint;
 274 }
 275
 276 /**
 277   Builds a HOB that describes a chunk of system memory.
 278
 279   This function builds a HOB that describes a chunk of system memory.
 280   It can only be invoked during PEI phase;
 281   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 282   If there is no additional space for HOB creation, then ASSERT().
 283
 284   @param  ResourceType        The type of resource described by this HOB.
 285   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 286   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 287   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 288
 289 **/
 290 VOID
 291 EFIAPI
 292 BuildResourceDescriptorHob (
 293   IN EFI_RESOURCE_TYPE            ResourceType,
 294   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 295   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 296   IN UINT64                       NumberOfBytes
 297   )
 298 {
 299   EFI_HOB_RESOURCE_DESCRIPTOR  *Hob;
 300
 301   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_RESOURCE_DESCRIPTOR, sizeof (EFI_HOB_RESOURCE_DESCRIPTOR));
 302
 303   Hob->ResourceType      = ResourceType;
 304   Hob->ResourceAttribute = ResourceAttribute;
 305   Hob->PhysicalStart     = PhysicalStart;
 306   Hob->ResourceLength    = NumberOfBytes;
 307 }
 308
 309 /**
 310   Builds a GUID HOB with a certain data length.
 311
 312   This function builds a customized HOB tagged with a GUID for identification
 313   and returns the start address of GUID HOB data so that caller can fill the customized data.
 314   The HOB Header and Name field is already stripped.
 315   It can only be invoked during PEI phase;
 316   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 317   If Guid is NULL, then ASSERT().
 318   If there is no additional space for HOB creation, then ASSERT().
 319   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 320
 321   @param  Guid          The GUID to tag the customized HOB.
 322   @param  DataLength    The size of the data payload for the GUID HOB.
 323
 324   @return The start address of GUID HOB data.
 325
 326 **/
 327 VOID *
 328 EFIAPI
 329 BuildGuidHob (
 330   IN CONST EFI_GUID              *Guid,
 331   IN UINTN                       DataLength
 332   )
 333 {
 334   EFI_HOB_GUID_TYPE *Hob;
 335
 336   //
 337   // Make sure that data length is not too long.
 338   //
 339   ASSERT (DataLength <= (0xffff - sizeof (EFI_HOB_GUID_TYPE)));
 340
 341   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_GUID_EXTENSION, (UINT16) (sizeof (EFI_HOB_GUID_TYPE) + DataLength));
 342   CopyGuid (&Hob->Name, Guid);
 343   return Hob + 1;
 344 }
 345
 346 /**
 347   Copies a data buffer to a newly-built HOB.
 348
 349   This function builds a customized HOB tagged with a GUID for identification,
 350   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 351   The HOB Header and Name field is already stripped.
 352   It can only be invoked during PEI phase;
 353   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 354   If Guid is NULL, then ASSERT().
 355   If Data is NULL and DataLength > 0, then ASSERT().
 356   If there is no additional space for HOB creation, then ASSERT().
 357   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 358
 359   @param  Guid          The GUID to tag the customized HOB.
 360   @param  Data          The data to be copied into the data field of the GUID HOB.
 361   @param  DataLength    The size of the data payload for the GUID HOB.
 362
 363   @return The start address of GUID HOB data.
 364
 365 **/
 366 VOID *
 367 EFIAPI
 368 BuildGuidDataHob (
 369   IN CONST EFI_GUID              *Guid,
 370   IN VOID                        *Data,
 371   IN UINTN                       DataLength
 372   )
 373 {
 374   VOID  *HobData;
 375
 376   ASSERT (Data != NULL || DataLength == 0);
 377
 378   HobData = BuildGuidHob (Guid, DataLength);
 379
 380   return CopyMem (HobData, Data, DataLength);
 381 }
 382
 383 /**
 384   Builds a Firmware Volume HOB.
 385
 386   This function builds a Firmware Volume HOB.
 387   It can only be invoked during PEI phase;
 388   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 389   If there is no additional space for HOB creation, then ASSERT().
 390
 391   @param  BaseAddress   The base address of the Firmware Volume.
 392   @param  Length        The size of the Firmware Volume in bytes.
 393
 394 **/
 395 VOID
 396 EFIAPI
 397 BuildFvHob (
 398   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 399   IN UINT64                      Length
 400   )
 401 {
 402   EFI_HOB_FIRMWARE_VOLUME  *Hob;
 403
 404   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_FV, sizeof (EFI_HOB_FIRMWARE_VOLUME));
 405
 406   Hob->BaseAddress = BaseAddress;
 407   Hob->Length      = Length;
 408 }
 409
 410 /**
 411   Builds a EFI_HOB_TYPE_FV2 HOB.
 412
 413   This function builds a EFI_HOB_TYPE_FV2 HOB.
 414   It can only be invoked during PEI phase;
 415   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 416   If there is no additional space for HOB creation, then ASSERT().
 417
 418   @param  BaseAddress   The base address of the Firmware Volume.
 419   @param  Length        The size of the Firmware Volume in bytes.
 420   @param  FvName       The name of the Firmware Volume.
 421   @param  FileName      The name of the file.
 422
 423 **/
 424 VOID
 425 EFIAPI
 426 BuildFv2Hob (
 427   IN          EFI_PHYSICAL_ADDRESS        BaseAddress,
 428   IN          UINT64                      Length,
 429   IN CONST    EFI_GUID                    *FvName,
 430   IN CONST    EFI_GUID                    *FileName
 431   )
 432 {
 433   EFI_HOB_FIRMWARE_VOLUME2  *Hob;
 434
 435   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_FV2, sizeof (EFI_HOB_FIRMWARE_VOLUME2));
 436
 437   Hob->BaseAddress = BaseAddress;
 438   Hob->Length      = Length;
 439   CopyGuid (&Hob->FvName, FvName);
 440   CopyGuid (&Hob->FileName, FileName);
 441 }
 442
 443 /**
 444   Builds a Capsule Volume HOB.
 445
 446   This function builds a Capsule Volume HOB.
 447   It can only be invoked during PEI phase;
 448   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 449   If there is no additional space for HOB creation, then ASSERT().
 450
 451   @param  BaseAddress   The base address of the Capsule Volume.
 452   @param  Length        The size of the Capsule Volume in bytes.
 453
 454 **/
 455 VOID
 456 EFIAPI
 457 BuildCvHob (
 458   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 459   IN UINT64                      Length
 460   )
 461 {
 462   ASSERT (FALSE);
 463 }
 464
 465 /**
 466   Builds a HOB for the CPU.
 467
 468   This function builds a HOB for the CPU.
 469   It can only be invoked during PEI phase;
 470   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 471   If there is no additional space for HOB creation, then ASSERT().
 472
 473   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 474   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 475
 476 **/
 477 VOID
 478 EFIAPI
 479 BuildCpuHob (
 480   IN UINT8                       SizeOfMemorySpace,
 481   IN UINT8                       SizeOfIoSpace
 482   )
 483 {
 484   EFI_HOB_CPU  *Hob;
 485
 486   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CPU, sizeof (EFI_HOB_CPU));
 487
 488   Hob->SizeOfMemorySpace = SizeOfMemorySpace;
 489   Hob->SizeOfIoSpace     = SizeOfIoSpace;
 490
 491   //
 492   // Zero the reserved space to match HOB spec
 493   //
 494   ZeroMem (Hob->Reserved, sizeof (Hob->Reserved));
 495 }
 496
 497 /**
 498   Builds a HOB for the Stack.
 499
 500   This function builds a HOB for the stack.
 501   It can only be invoked during PEI phase;
 502   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 503   If there is no additional space for HOB creation, then ASSERT().
 504
 505   @param  BaseAddress   The 64 bit physical address of the Stack.
 506   @param  Length        The length of the stack in bytes.
 507
 508 **/
 509 VOID
 510 EFIAPI
 511 BuildStackHob (
 512   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 513   IN UINT64                      Length
 514   )
 515 {
 516   EFI_HOB_MEMORY_ALLOCATION_STACK  *Hob;
 517
 518   ASSERT (((BaseAddress & (EFI_PAGE_SIZE - 1)) == 0) &&
 519           ((Length & (EFI_PAGE_SIZE - 1)) == 0));
 520
 521   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_STACK));
 522
 523   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocStackGuid);
 524   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 525   Hob->AllocDescriptor.MemoryLength      = Length;
 526   Hob->AllocDescriptor.MemoryType        = EfiBootServicesData;
 527
 528   //
 529   // Zero the reserved space to match HOB spec
 530   //
 531   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 532 }
 533
 534 /**
 535   Builds a HOB for the BSP store.
 536
 537   This function builds a HOB for BSP store.
 538   It can only be invoked during PEI phase;
 539   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 540   If there is no additional space for HOB creation, then ASSERT().
 541
 542   @param  BaseAddress   The 64 bit physical address of the BSP.
 543   @param  Length        The length of the BSP store in bytes.
 544   @param  MemoryType    Type of memory allocated by this HOB.
 545
 546 **/
 547 VOID
 548 EFIAPI
 549 BuildBspStoreHob (
 550   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 551   IN UINT64                      Length,
 552   IN EFI_MEMORY_TYPE             MemoryType
 553   )
 554 {
 555   EFI_HOB_MEMORY_ALLOCATION_BSP_STORE  *Hob;
 556
 557   ASSERT (((BaseAddress & (EFI_PAGE_SIZE - 1)) == 0) &&
 558           ((Length & (EFI_PAGE_SIZE - 1)) == 0));
 559
 560   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_BSP_STORE));
 561
 562   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocBspStoreGuid);
 563   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 564   Hob->AllocDescriptor.MemoryLength      = Length;
 565   Hob->AllocDescriptor.MemoryType        = MemoryType;
 566
 567   //
 568   // Zero the reserved space to match HOB spec
 569   //
 570   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 571 }
 572
 573 /**
 574   Builds a HOB for the memory allocation.
 575
 576   This function builds a HOB for the memory allocation.
 577   It can only be invoked during PEI phase;
 578   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 579   If there is no additional space for HOB creation, then ASSERT().
 580
 581   @param  BaseAddress   The 64 bit physical address of the memory.
 582   @param  Length        The length of the memory allocation in bytes.
 583   @param  MemoryType    Type of memory allocated by this HOB.
 584
 585 **/
 586 VOID
 587 EFIAPI
 588 BuildMemoryAllocationHob (
 589   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 590   IN UINT64                      Length,
 591   IN EFI_MEMORY_TYPE             MemoryType
 592   )
 593 {
 594   EFI_HOB_MEMORY_ALLOCATION  *Hob;
 595
 596   ASSERT (((BaseAddress & (EFI_PAGE_SIZE - 1)) == 0) &&
 597           ((Length & (EFI_PAGE_SIZE - 1)) == 0));
 598
 599   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION));
 600
 601   ZeroMem (&(Hob->AllocDescriptor.Name), sizeof (EFI_GUID));
 602   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 603   Hob->AllocDescriptor.MemoryLength      = Length;
 604   Hob->AllocDescriptor.MemoryType        = MemoryType;
 605   //
 606   // Zero the reserved space to match HOB spec
 607   //
 608   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 609 }