MdePkg/Include/Library/HobLib.h

   1 /** @file
   2         Public include file for the HOB Library
   3
   4         Copyright (c) 2006, Intel Corporation
   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.h
  14
  15 **/
  16
  17 #ifndef __HOB_LIB_H__
  18 #define __HOB_LIB_H__
  19
  20 /**
  21         Returns the pointer to the HOB list.
  22
  23         @return The pointer to the HOB list.
  24
  25 **/
  26 VOID *
  27 EFIAPI
  28 GetHobList (
  29   VOID
  30   )
  31 ;
  32
  33 /**
  34         This function searches the first instance of a HOB type from the starting HOB pointer.
  35         If there does not exist such HOB type from the starting HOB pointer, it will return NULL.
  36
  37         @param  Type The HOB type to return.
  38         @param  HobStart The starting HOB pointer to search from.
  39
  40         @return The next instance of a HOB type from the starting HOB.
  41
  42 **/
  43 VOID *
  44 EFIAPI
  45 GetNextHob (
  46   IN UINT16                 Type,
  47   IN CONST VOID             *HobStart
  48   )
  49 ;
  50
  51 /**
  52         This function searches the first instance of a HOB type among the whole HOB list.
  53         If there does not exist such HOB type in the HOB list, it will return NULL.
  54
  55         @param  Type The HOB type to return.
  56
  57         @return The next instance of a HOB type from the starting HOB.
  58
  59 **/
  60 VOID *
  61 EFIAPI
  62 GetFirstHob (
  63   IN UINT16                 Type
  64   )
  65 ;
  66
  67 /**
  68         This function searches the first instance of a HOB from the starting HOB pointer.
  69         Such HOB should satisfy two conditions:
  70         its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
  71         If there does not exist such HOB from the starting HOB pointer, it will return NULL.
  72
  73         @param  Guid The GUID to match with in the HOB list.
  74         @param  HobStart A pointer to a Guid.
  75
  76         @return The next instance of the matched GUID HOB from the starting HOB.
  77
  78 **/
  79 VOID *
  80 EFIAPI
  81 GetNextGuidHob (
  82   IN CONST EFI_GUID         *Guid,
  83   IN CONST VOID             *HobStart
  84   )
  85 ;
  86
  87 /**
  88         This function searches the first instance of a HOB among the whole HOB list.
  89         Such HOB should satisfy two conditions:
  90         its HOB type is EFI_HOB_TYPE_GUID_EXTENSION and its GUID Name equals to the input Guid.
  91         If there does not exist such HOB from the starting HOB pointer, it will return NULL.
  92
  93         @param  Guid The GUID to match with in the HOB list.
  94
  95         @return The first instance of the matched GUID HOB among the whole HOB list.
  96
  97 **/
  98 VOID *
  99 EFIAPI
 100 GetFirstGuidHob (
 101   IN CONST EFI_GUID         *Guid
 102   )
 103 ;
 104
 105 /**
 106         This function builds a HOB for a loaded PE32 module.
 107
 108         @param  ModuleName The GUID File Name of the module.
 109         @param  MemoryAllocationModule The 64 bit physical address of the module.
 110         @param  ModuleLength The length of the module in bytes.
 111         @param  EntryPoint The 64 bit physical address of the module\92s entry point.
 112
 113 **/
 114 VOID
 115 EFIAPI
 116 BuildModuleHob (
 117   IN CONST EFI_GUID         *ModuleName,
 118   IN EFI_PHYSICAL_ADDRESS   MemoryAllocationModule,
 119   IN UINT64                 ModuleLength,
 120   IN EFI_PHYSICAL_ADDRESS   EntryPoint
 121   )
 122 ;
 123
 124 /**
 125         Builds a HOB that describes a chunk of system memory.
 126
 127         @param  ResourceType The type of resource described by this HOB.
 128         @param  ResourceAttribute The resource attributes of the memory described by this HOB.
 129         @param  PhysicalStart The 64 bit physical address of memory described by this HOB.
 130         @param  NumberOfBytes The length of the memory described by this HOB in bytes.
 131
 132 **/
 133 VOID
 134 EFIAPI
 135 BuildResourceDescriptorHob (
 136   IN EFI_RESOURCE_TYPE            ResourceType,
 137   IN EFI_RESOURCE_ATTRIBUTE_TYPE  ResourceAttribute,
 138   IN EFI_PHYSICAL_ADDRESS         PhysicalStart,
 139   IN UINT64                       NumberOfBytes
 140   )
 141 ;
 142
 143 /**
 144         This function builds a customized HOB tagged with a GUID for identification
 145         and returns the start address of GUID HOB data so that caller can fill the customized data.
 146
 147         @param  Guid The GUID to tag the customized HOB.
 148         @param  DataLength The size of the data payload for the GUID HOB.
 149
 150         @return The start address of GUID HOB data.
 151
 152 **/
 153 VOID *
 154 EFIAPI
 155 BuildGuidHob (
 156   IN CONST EFI_GUID              *Guid,
 157   IN UINTN                       DataLength
 158   )
 159 ;
 160
 161 /**
 162         This function builds a customized HOB tagged with a GUID for identification,
 163         copies the input data to the HOB data field, and returns the start address of GUID HOB data.
 164
 165         @param  Guid The GUID to tag the customized HOB.
 166         @param  Data The data to be copied into the data field of the GUID HOB.
 167         @param  DataLength The size of the data payload for the GUID HOB.
 168
 169         @return The start address of GUID HOB data.
 170
 171 **/
 172 VOID *
 173 EFIAPI
 174 BuildGuidDataHob (
 175   IN CONST EFI_GUID              *Guid,
 176   IN VOID                        *Data,
 177   IN UINTN                       DataLength
 178   )
 179 ;
 180
 181 /**
 182         Builds a Firmware Volume HOB.
 183
 184         @param  BaseAddress The base address of the Firmware Volume.
 185         @param  Length The size of the Firmware Volume in bytes.
 186
 187 **/
 188 VOID
 189 EFIAPI
 190 BuildFvHob (
 191   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 192   IN UINT64                      Length
 193   )
 194 ;
 195
 196 /**
 197         Builds a Capsule Volume HOB.
 198
 199         @param  BaseAddress The base address of the Capsule Volume.
 200         @param  Length The size of the Capsule Volume in bytes.
 201
 202 **/
 203 VOID
 204 EFIAPI
 205 BuildCvHob (
 206   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 207   IN UINT64                      Length
 208   )
 209 ;
 210
 211 /**
 212         Builds a HOB for the CPU.
 213
 214         @param  SizeOfMemorySpace The maximum physical memory addressability of the processor.
 215         @param  SizeOfIoSpace The maximum physical I/O addressability of the processor.
 216
 217 **/
 218 VOID
 219 EFIAPI
 220 BuildCpuHob (
 221   IN UINT8                       SizeOfMemorySpace,
 222   IN UINT8                       SizeOfIoSpace
 223   )
 224 ;
 225
 226 /**
 227         Builds a HOB for the Stack.
 228
 229         @param  BaseAddress The 64 bit physical address of the Stack.
 230         @param  Length The length of the stack in bytes.
 231
 232 **/
 233 VOID
 234 EFIAPI
 235 BuildStackHob (
 236   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 237   IN UINT64                      Length
 238   )
 239 ;
 240
 241 /**
 242         Builds a HOB for the BSP store.
 243
 244         @param  BaseAddress The 64 bit physical address of the BSP.
 245         @param  Length The length of the BSP store in bytes.
 246         @param  MemoryType Type of memory allocated by this HOB.
 247
 248 **/
 249 VOID
 250 EFIAPI
 251 BuildBspStoreHob (
 252   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 253   IN UINT64                      Length,
 254   IN EFI_MEMORY_TYPE             MemoryType
 255   )
 256 ;
 257
 258 /**
 259         Builds a HOB for the memory allocation.
 260
 261         @param  BaseAddress The 64 bit physical address of the memory.
 262         @param  Length The length of the memory allocation in bytes.
 263         @param  MemoryType Type of memory allocated by this HOB.
 264
 265 **/
 266 VOID
 267 EFIAPI
 268 BuildMemoryAllocationHob (
 269   IN EFI_PHYSICAL_ADDRESS        BaseAddress,
 270   IN UINT64                      Length,
 271   IN EFI_MEMORY_TYPE             MemoryType
 272   )
 273 ;
 274
 275 #endif