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 = PeiServicesGetHobList (&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 = PeiServicesCreateHob (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's 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   //
 232   // Zero the reserved space to match HOB spec
 233   //
 234   ZeroMem (Hob->MemoryAllocationHeader.Reserved, sizeof (Hob->MemoryAllocationHeader.Reserved));
 235
 236   CopyGuid (&Hob->ModuleName, ModuleName);
 237   Hob->EntryPoint = EntryPoint;
 238 }
 239
 240 /**
 241   Builds a HOB that describes a chunk of system memory.
 242
 243   This function builds a HOB that describes a chunk of system memory.
 244   It can only be invoked during PEI phase;
 245   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 246   If there is no additional space for HOB creation, then ASSERT().
 247
 248   @param  ResourceType        The type of resource described by this HOB.
 249   @param  ResourceAttribute   The resource attributes of the memory described by this HOB.
 250   @param  PhysicalStart       The 64 bit physical address of memory described by this HOB.
 251   @param  NumberOfBytes       The length of the memory described by this HOB in bytes.
 252
 253 **/
 254 VOID
 255 EFIAPI
 256 BuildResourceDescriptorHob (
 257   IN EFI_RESOURCE_TYPE            ResourceType,
 258   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 259   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 260   IN UINT64                       NumberOfBytes
 261   )
 262 {
 263   EFI_HOB_RESOURCE_DESCRIPTOR  *Hob;
 264
 265   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_RESOURCE_DESCRIPTOR, sizeof (EFI_HOB_RESOURCE_DESCRIPTOR));
 266
 267   Hob->ResourceType      = ResourceType;
 268   Hob->ResourceAttribute = ResourceAttribute;
 269   Hob->PhysicalStart     = PhysicalStart;
 270   Hob->ResourceLength    = NumberOfBytes;
 271 }
 272
 273 /**
 274   Builds a GUID HOB with a certain data length.
 275
 276   This function builds a customized HOB tagged with a GUID for identification
 277   and returns the start address of GUID HOB data so that caller can fill the customized data.
 278   The HOB Header and Name field is already stripped.
 279   It can only be invoked during PEI phase;
 280   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 281   If Guid is NULL, then ASSERT().
 282   If there is no additional space for HOB creation, then ASSERT().
 283   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 284
 285   @param  Guid          The GUID to tag the customized HOB.
 286   @param  DataLength    The size of the data payload for the GUID HOB.
 287
 288   @return The start address of GUID HOB data.
 289
 290 **/
 291 VOID *
 292 EFIAPI
 293 BuildGuidHob (
 294   IN CONST EFI_GUID              *Guid,
 295   IN UINTN                       DataLength
 296   )
 297 {
 298   EFI_HOB_GUID_TYPE *Hob;
 299
 300   //
 301   // Make sure that data length is not too long.
 302   //
 303   ASSERT (DataLength <= (0xffff - sizeof (EFI_HOB_GUID_TYPE)));
 304
 305   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_GUID_EXTENSION, (UINT16) (sizeof (EFI_HOB_GUID_TYPE) + DataLength));
 306   CopyGuid (&Hob->Name, Guid);
 307   return Hob + 1;
 308 }
 309
 310 /**
 311   Copies a data buffer to a newly-built HOB.
 312
 313   This function builds a customized HOB tagged with a GUID for identification,
 314   copies the input data to the HOB data field and returns the start address of the GUID HOB data.
 315   The HOB Header and Name field is already stripped.
 316   It can only be invoked during PEI phase;
 317   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 318   If Guid is NULL, then ASSERT().
 319   If Data is NULL and DataLength > 0, then ASSERT().
 320   If there is no additional space for HOB creation, then ASSERT().
 321   If DataLength >= (0x10000 - sizeof (EFI_HOB_GUID_TYPE)), then ASSERT().
 322
 323   @param  Guid          The GUID to tag the customized HOB.
 324   @param  Data          The data to be copied into the data field of the GUID HOB.
 325   @param  DataLength    The size of the data payload for the GUID HOB.
 326
 327   @return The start address of GUID HOB data.
 328
 329 **/
 330 VOID *
 331 EFIAPI
 332 BuildGuidDataHob (
 333   IN CONST EFI_GUID              *Guid,
 334   IN VOID                        *Data,
 335   IN UINTN                       DataLength
 336   )
 337 {
 338   VOID  *HobData;
 339
 340   ASSERT (Data != NULL || DataLength == 0);
 341
 342   HobData = BuildGuidHob (Guid, DataLength);
 343
 344   return CopyMem (HobData, Data, DataLength);
 345 }
 346
 347 /**
 348   Builds a Firmware Volume HOB.
 349
 350   This function builds a Firmware Volume HOB.
 351   It can only be invoked during PEI phase;
 352   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 353   If there is no additional space for HOB creation, then ASSERT().
 354
 355   @param  BaseAddress   The base address of the Firmware Volume.
 356   @param  Length        The size of the Firmware Volume in bytes.
 357
 358 **/
 359 VOID
 360 EFIAPI
 361 BuildFvHob (
 362   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 363   IN UINT64                      Length
 364   )
 365 {
 366   EFI_HOB_FIRMWARE_VOLUME  *Hob;
 367
 368   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_FV, sizeof (EFI_HOB_FIRMWARE_VOLUME));
 369
 370   Hob->BaseAddress = BaseAddress;
 371   Hob->Length      = Length;
 372 }
 373
 374 /**
 375   Builds a Capsule Volume HOB.
 376
 377   This function builds a Capsule Volume HOB.
 378   It can only be invoked during PEI phase;
 379   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 380   If there is no additional space for HOB creation, then ASSERT().
 381
 382   @param  BaseAddress   The base address of the Capsule Volume.
 383   @param  Length        The size of the Capsule Volume in bytes.
 384
 385 **/
 386 VOID
 387 EFIAPI
 388 BuildCvHob (
 389   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 390   IN UINT64                      Length
 391   )
 392 {
 393   EFI_HOB_CAPSULE_VOLUME  *Hob;
 394
 395   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CV, sizeof (EFI_HOB_CAPSULE_VOLUME));
 396
 397   Hob->BaseAddress  = BaseAddress;
 398   Hob->Length       = Length;
 399 }
 400
 401 /**
 402   Builds a HOB for the CPU.
 403
 404   This function builds a HOB for the CPU.
 405   It can only be invoked during PEI phase;
 406   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 407   If there is no additional space for HOB creation, then ASSERT().
 408
 409   @param  SizeOfMemorySpace   The maximum physical memory addressability of the processor.
 410   @param  SizeOfIoSpace       The maximum physical I/O addressability of the processor.
 411
 412 **/
 413 VOID
 414 EFIAPI
 415 BuildCpuHob (
 416   IN UINT8                       SizeOfMemorySpace,
 417   IN UINT8                       SizeOfIoSpace
 418   )
 419 {
 420   EFI_HOB_CPU  *Hob;
 421
 422   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_CPU, sizeof (EFI_HOB_CPU));
 423
 424   Hob->SizeOfMemorySpace = SizeOfMemorySpace;
 425   Hob->SizeOfIoSpace     = SizeOfIoSpace;
 426
 427   //
 428   // Zero the reserved space to match HOB spec
 429   //
 430   ZeroMem (Hob->Reserved, sizeof (Hob->Reserved));
 431 }
 432
 433 /**
 434   Builds a HOB for the Stack.
 435
 436   This function builds a HOB for the stack.
 437   It can only be invoked during PEI phase;
 438   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 439   If there is no additional space for HOB creation, then ASSERT().
 440
 441   @param  BaseAddress   The 64 bit physical address of the Stack.
 442   @param  Length        The length of the stack in bytes.
 443
 444 **/
 445 VOID
 446 EFIAPI
 447 BuildStackHob (
 448   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 449   IN UINT64                      Length
 450   )
 451 {
 452   EFI_HOB_MEMORY_ALLOCATION_STACK  *Hob;
 453
 454   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_STACK));
 455
 456   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocStackGuid);
 457   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 458   Hob->AllocDescriptor.MemoryLength      = Length;
 459   Hob->AllocDescriptor.MemoryType        = EfiConventionalMemory;
 460
 461   //
 462   // Zero the reserved space to match HOB spec
 463   //
 464   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 465 }
 466
 467 /**
 468   Builds a HOB for the BSP store.
 469
 470   This function builds a HOB for BSP store.
 471   It can only be invoked during PEI phase;
 472   for DXE phase, it will ASSERT() since PEI HOB is read-only for DXE phase.
 473   If there is no additional space for HOB creation, then ASSERT().
 474
 475   @param  BaseAddress   The 64 bit physical address of the BSP.
 476   @param  Length        The length of the BSP store in bytes.
 477   @param  MemoryType    Type of memory allocated by this HOB.
 478
 479 **/
 480 VOID
 481 EFIAPI
 482 BuildBspStoreHob (
 483   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 484   IN UINT64                      Length,
 485   IN EFI_MEMORY_TYPE             MemoryType
 486   )
 487 {
 488   EFI_HOB_MEMORY_ALLOCATION_BSP_STORE  *Hob;
 489
 490   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION_BSP_STORE));
 491
 492   CopyGuid (&(Hob->AllocDescriptor.Name), &gEfiHobMemoryAllocBspStoreGuid);
 493   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 494   Hob->AllocDescriptor.MemoryLength      = Length;
 495   Hob->AllocDescriptor.MemoryType        = MemoryType;
 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 memory allocation.
 505
 506   This function builds a HOB for the memory allocation.
 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 memory.
 512   @param  Length        The length of the memory allocation in bytes.
 513   @param  MemoryType    Type of memory allocated by this HOB.
 514
 515 **/
 516 VOID
 517 EFIAPI
 518 BuildMemoryAllocationHob (
 519   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 520   IN UINT64                      Length,
 521   IN EFI_MEMORY_TYPE             MemoryType
 522   )
 523 {
 524   EFI_HOB_MEMORY_ALLOCATION  *Hob;
 525
 526   Hob = InternalPeiCreateHob (EFI_HOB_TYPE_MEMORY_ALLOCATION, sizeof (EFI_HOB_MEMORY_ALLOCATION));
 527
 528   ZeroMem (&(Hob->AllocDescriptor.Name), sizeof (EFI_GUID));
 529   Hob->AllocDescriptor.MemoryBaseAddress = BaseAddress;
 530   Hob->AllocDescriptor.MemoryLength      = Length;
 531   Hob->AllocDescriptor.MemoryType        = MemoryType;
 532   //
 533   // Zero the reserved space to match HOB spec
 534   //
 535   ZeroMem (Hob->AllocDescriptor.Reserved, sizeof (Hob->AllocDescriptor.Reserved));
 536 }