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