1 /** @file 2 Provides library functions for all PEI Services. 3 4 Copyright (c) 2006 - 2008, Intel Corporation. All rights reserved.<BR> 5 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 #ifndef __PEI_SERVICES_LIB_H__ 16 #define __PEI_SERVICES_LIB_H__ 17 18 /** 19 This service enables a given PEIM to register an interface into the PEI Foundation. 20 21 @param PpiList A pointer to the list of interfaces that the caller shall install. 22 23 @retval EFI_SUCCESS The interface was successfully installed. 24 @retval EFI_INVALID_PARAMETER The PpiList pointer is NULL. 25 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the 26 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field. 27 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 28 29 **/ 30 EFI_STATUS 31 EFIAPI 32 PeiServicesInstallPpi ( 33 IN CONST EFI_PEI_PPI_DESCRIPTOR *PpiList 34 ); 35 36 /** 37 This service enables PEIMs to replace an entry in the PPI database with an alternate entry. 38 39 @param OldPpi Pointer to the old PEI PPI Descriptors. 40 @param NewPpi Pointer to the new PEI PPI Descriptors. 41 42 @retval EFI_SUCCESS The interface was successfully installed. 43 @retval EFI_INVALID_PARAMETER The OldPpi or NewPpi is NULL. 44 @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the 45 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field. 46 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 47 @retval EFI_NOT_FOUND The PPI for which the reinstallation was requested has not been 48 installed. 49 50 **/ 51 EFI_STATUS 52 EFIAPI 53 PeiServicesReInstallPpi ( 54 IN CONST EFI_PEI_PPI_DESCRIPTOR *OldPpi, 55 IN CONST EFI_PEI_PPI_DESCRIPTOR *NewPpi 56 ); 57 58 /** 59 This service enables PEIMs to discover a given instance of an interface. 60 61 @param Guid A pointer to the GUID whose corresponding interface needs to be 62 found. 63 @param Instance The N-th instance of the interface that is required. 64 @param PpiDescriptor A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR. 65 @param Ppi A pointer to the instance of the interface. 66 67 @retval EFI_SUCCESS The interface was successfully returned. 68 @retval EFI_NOT_FOUND The PPI descriptor is not found in the database. 69 70 **/ 71 EFI_STATUS 72 EFIAPI 73 PeiServicesLocatePpi ( 74 IN CONST EFI_GUID *Guid, 75 IN UINTN Instance, 76 IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor, 77 IN OUT VOID **Ppi 78 ); 79 80 /** 81 This service enables PEIMs to register a given service to be invoked when another service is 82 installed or reinstalled. 83 84 @param NotifyList A pointer to the list of notification interfaces that the caller 85 shall install. 86 87 @retval EFI_SUCCESS The interface was successfully installed. 88 @retval EFI_INVALID_PARAMETER The NotifyList pointer is NULL. 89 @retval EFI_INVALID_PARAMETER Any of the PEI notify descriptors in the list do not have the 90 EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field. 91 @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database. 92 93 **/ 94 EFI_STATUS 95 EFIAPI 96 PeiServicesNotifyPpi ( 97 IN CONST EFI_PEI_NOTIFY_DESCRIPTOR *NotifyList 98 ); 99 100 /** 101 This service enables PEIMs to ascertain the present value of the boot mode. 102 103 @param BootMode A pointer to contain the value of the boot mode. 104 105 @retval EFI_SUCCESS The boot mode was returned successfully. 106 @retval EFI_INVALID_PARAMETER BootMode is NULL. 107 108 **/ 109 EFI_STATUS 110 EFIAPI 111 PeiServicesGetBootMode ( 112 OUT EFI_BOOT_MODE *BootMode 113 ); 114 115 /** 116 This service enables PEIMs to update the boot mode variable. 117 118 @param BootMode The value of the boot mode to set. 119 120 @retval EFI_SUCCESS The value was successfully updated 121 122 **/ 123 EFI_STATUS 124 EFIAPI 125 PeiServicesSetBootMode ( 126 IN EFI_BOOT_MODE BootMode 127 ); 128 129 /** 130 This service enables a PEIM to ascertain the address of the list of HOBs in memory. 131 132 @param HobList A pointer to the list of HOBs that the PEI Foundation will initialize. 133 134 @retval EFI_SUCCESS The list was successfully returned. 135 @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published. 136 137 **/ 138 EFI_STATUS 139 EFIAPI 140 PeiServicesGetHobList ( 141 OUT VOID **HobList 142 ); 143 144 /** 145 This service enables PEIMs to create various types of HOBs. 146 147 @param Type The type of HOB to be installed. 148 @param Length The length of the HOB to be added. 149 @param Hob The address of a pointer that will contain the HOB header. 150 151 @retval EFI_SUCCESS The HOB was successfully created. 152 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation. 153 154 **/ 155 EFI_STATUS 156 EFIAPI 157 PeiServicesCreateHob ( 158 IN UINT16 Type, 159 IN UINT16 Length, 160 OUT VOID **Hob 161 ); 162 163 /** 164 This service enables PEIMs to discover additional firmware volumes. 165 166 @param Instance This instance of the firmware volume to find. The value 0 is the 167 Boot Firmware Volume (BFV). 168 @param VolumeHandle Handle of the firmware volume header of the volume to return. 169 170 @retval EFI_SUCCESS The volume was found. 171 @retval EFI_NOT_FOUND The volume was not found. 172 @retval EFI_INVALID_PARAMETER FwVolHeader is NULL. 173 174 **/ 175 EFI_STATUS 176 EFIAPI 177 PeiServicesFfsFindNextVolume ( 178 IN UINTN Instance, 179 IN OUT EFI_PEI_FV_HANDLE *VolumeHandle 180 ); 181 182 /** 183 This service enables PEIMs to discover additional firmware files. 184 185 @param SearchType A filter to find files only of this type. 186 @param VolumeHandle Pointer to the firmware volume header of the volume to search. 187 This parameter must point to a valid FFS volume. 188 @param FileHandle Handle of the current file from which to begin searching. 189 190 @retval EFI_SUCCESS The file was found. 191 @retval EFI_NOT_FOUND The file was not found. 192 @retval EFI_NOT_FOUND The header checksum was not zero. 193 194 **/ 195 EFI_STATUS 196 EFIAPI 197 PeiServicesFfsFindNextFile ( 198 IN EFI_FV_FILETYPE SearchType, 199 IN EFI_PEI_FV_HANDLE VolumeHandle, 200 IN OUT EFI_PEI_FILE_HANDLE *FileHandle 201 ); 202 203 /** 204 This service enables PEIMs to discover sections of a given type within a valid FFS file. 205 206 @param SectionType The value of the section type to find. 207 @param FileHandle A pointer to the file header that contains the set of sections to 208 be searched. 209 @param SectionData A pointer to the discovered section, if successful. 210 211 @retval EFI_SUCCESS The section was found. 212 @retval EFI_NOT_FOUND The section was not found. 213 214 **/ 215 EFI_STATUS 216 EFIAPI 217 PeiServicesFfsFindSectionData ( 218 IN EFI_SECTION_TYPE SectionType, 219 IN EFI_PEI_FILE_HANDLE FileHandle, 220 OUT VOID **SectionData 221 ); 222 223 /** 224 This service enables PEIMs to discover sections of a given instance and type within a valid FFS file. 225 226 @param SectionType The value of the section type to find. 227 @param SectionInstance Section instance to find. 228 @param FileHandle A pointer to the file header that contains the set 229 of sections to be searched. 230 @param SectionData A pointer to the discovered section, if successful. 231 @param AuthenticationStatus A pointer to the authentication status for this section. 232 233 @retval EFI_SUCCESS The section was found. 234 @retval EFI_NOT_FOUND The section was not found. 235 236 **/ 237 EFI_STATUS 238 EFIAPI 239 PeiServicesFfsFindSectionData3 ( 240 IN EFI_SECTION_TYPE SectionType, 241 IN UINTN SectionInstance, 242 IN EFI_PEI_FILE_HANDLE FileHandle, 243 OUT VOID **SectionData, 244 OUT UINT32 *AuthenticationStatus 245 ); 246 247 /** 248 This service enables PEIMs to register the permanent memory configuration 249 that has been initialized with the PEI Foundation. 250 251 @param MemoryBegin The value of a region of installed memory. 252 @param MemoryLength The corresponding length of a region of installed memory. 253 254 @retval EFI_SUCCESS The region was successfully installed in a HOB. 255 @retval EFI_INVALID_PARAMETER MemoryBegin and MemoryLength are illegal for this system. 256 @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation. 257 258 **/ 259 EFI_STATUS 260 EFIAPI 261 PeiServicesInstallPeiMemory ( 262 IN EFI_PHYSICAL_ADDRESS MemoryBegin, 263 IN UINT64 MemoryLength 264 ); 265 266 /** 267 This service enables PEIMs to allocate memory after the permanent memory has been installed by a 268 PEIM. 269 270 @param MemoryType Type of memory to allocate. 271 @param Pages Number of pages to allocate. 272 @param Memory Pointer of memory allocated. 273 274 @retval EFI_SUCCESS The memory range was successfully allocated. 275 @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages. 276 @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available. 277 @retval EFI_OUT_OF_RESOURCES The pages could not be allocated. 278 279 **/ 280 EFI_STATUS 281 EFIAPI 282 PeiServicesAllocatePages ( 283 IN EFI_MEMORY_TYPE MemoryType, 284 IN UINTN Pages, 285 OUT EFI_PHYSICAL_ADDRESS *Memory 286 ); 287 288 /** 289 This service allocates memory from the Hand-Off Block (HOB) heap. 290 291 @param Size The number of bytes to allocate from the pool. 292 @param Buffer If the call succeeds, a pointer to a pointer to the allocate 293 buffer; undefined otherwise. 294 295 @retval EFI_SUCCESS The allocation was successful 296 @retval EFI_OUT_OF_RESOURCES There is not enough heap to allocate the requested size. 297 298 **/ 299 EFI_STATUS 300 EFIAPI 301 PeiServicesAllocatePool ( 302 IN UINTN Size, 303 OUT VOID **Buffer 304 ); 305 306 /** 307 Resets the entire platform. 308 309 @retval EFI_SUCCESS The function completed successfully. 310 @retval EFI_NOT_AVAILABLE_YET The service has not been installed yet. 311 312 **/ 313 EFI_STATUS 314 EFIAPI 315 PeiServicesResetSystem ( 316 VOID 317 ); 318 319 320 /** 321 This service is a wrapper for the PEI Service FfsFindByName(), except the pointer to the PEI Services 322 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 323 Specification for details. 324 325 @param FileName A pointer to the name of the file to 326 find within the firmware volume. 327 328 @param VolumeHandle The firmware volume to search FileHandle 329 Upon exit, points to the found file's 330 handle or NULL if it could not be found. 331 @param FileHandle Pointer to found file handle 332 333 @retval EFI_SUCCESS File was found. 334 335 @retval EFI_NOT_FOUND File was not found. 336 337 @retval EFI_INVALID_PARAMETER VolumeHandle or FileHandle or 338 FileName was NULL. 339 340 **/ 341 EFI_STATUS 342 EFIAPI 343 PeiServicesFfsFindFileByName ( 344 IN CONST EFI_GUID *FileName, 345 IN CONST EFI_PEI_FV_HANDLE VolumeHandle, 346 OUT EFI_PEI_FILE_HANDLE *FileHandle 347 ); 348 349 350 /** 351 This service is a wrapper for the PEI Service FfsGetFileInfo(), except the pointer to the PEI Services 352 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 353 Specification for details. 354 355 @param FileHandle Handle of the file. 356 357 @param FileInfo Upon exit, points to the file's 358 information. 359 360 @retval EFI_SUCCESS File information returned. 361 362 @retval EFI_INVALID_PARAMETER If FileHandle does not 363 represent a valid file. 364 365 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 366 367 **/ 368 EFI_STATUS 369 EFIAPI 370 PeiServicesFfsGetFileInfo ( 371 IN CONST EFI_PEI_FILE_HANDLE FileHandle, 372 OUT EFI_FV_FILE_INFO *FileInfo 373 ); 374 375 /** 376 This service is a wrapper for the PEI Service FfsGetFileInfo2(), except the pointer to the PEI Services 377 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 378 Specification for details. 379 380 @param FileHandle Handle of the file. 381 382 @param FileInfo Upon exit, points to the file's 383 information. 384 385 @retval EFI_SUCCESS File information returned. 386 387 @retval EFI_INVALID_PARAMETER If FileHandle does not 388 represent a valid file. 389 390 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 391 392 **/ 393 EFI_STATUS 394 EFIAPI 395 PeiServicesFfsGetFileInfo2 ( 396 IN CONST EFI_PEI_FILE_HANDLE FileHandle, 397 OUT EFI_FV_FILE_INFO2 *FileInfo 398 ); 399 400 /** 401 This service is a wrapper for the PEI Service FfsGetVolumeInfo(), except the pointer to the PEI Services 402 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 403 Specification for details. 404 405 @param VolumeHandle Handle of the volume. 406 407 @param VolumeInfo Upon exit, points to the volume's 408 information. 409 410 @retval EFI_SUCCESS File information returned. 411 412 @retval EFI_INVALID_PARAMETER If FileHandle does not 413 represent a valid file. 414 415 @retval EFI_INVALID_PARAMETER If FileInfo is NULL. 416 417 **/ 418 EFI_STATUS 419 EFIAPI 420 PeiServicesFfsGetVolumeInfo ( 421 IN EFI_PEI_FV_HANDLE VolumeHandle, 422 OUT EFI_FV_INFO *VolumeInfo 423 ); 424 425 426 /** 427 This service is a wrapper for the PEI Service RegisterForShadow(), except the pointer to the PEI Services 428 Table has been removed. See the Platform Initialization Pre-EFI Initialization Core Interface 429 Specification for details. 430 431 @param FileHandle PEIM's file handle. Must be the currently 432 executing PEIM. 433 434 @retval EFI_SUCCESS The PEIM was successfully registered for 435 shadowing. 436 437 @retval EFI_ALREADY_STARTED The PEIM was previously 438 registered for shadowing. 439 440 @retval EFI_NOT_FOUND The FileHandle does not refer to a 441 valid file handle. 442 **/ 443 EFI_STATUS 444 EFIAPI 445 PeiServicesRegisterForShadow ( 446 IN EFI_PEI_FILE_HANDLE FileHandle 447 ); 448 449 /** 450 Install a EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance so the PEI Core will be notified about a new firmware volume. 451 452 This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO_PPI using 453 the parameters passed in to initialize the fields of the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI instance. 454 If the resources can not be allocated for EFI_PEI_FIRMWARE_VOLUME_INFO_PPI, then ASSERT(). 455 If the EFI_PEI_FIRMWARE_VOLUME_INFO_PPI can not be installed, then ASSERT(). 456 457 458 @param FvFormat Unique identifier of the format of the memory-mapped firmware volume. 459 This parameter is optional and may be NULL. 460 If NULL is specified, the EFI_FIRMWARE_FILE_SYSTEM2_GUID format is assumed. 461 @param FvInfo Points to a buffer which allows the EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. 462 The format of this buffer is specific to the FvFormat. For memory-mapped firmware volumes, 463 this typically points to the first byte of the firmware volume. 464 @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped firmware volumes, 465 this is typically the size of the firmware volume. 466 @param ParentFvName If the new firmware volume originated from a file in a different firmware volume, 467 then this parameter specifies the GUID name of the originating firmware volume. 468 Otherwise, this parameter must be NULL. 469 @param ParentFileName If the new firmware volume originated from a file in a different firmware volume, 470 then this parameter specifies the GUID file name of the originating firmware file. 471 Otherwise, this parameter must be NULL. 472 **/ 473 VOID 474 EFIAPI 475 PeiServicesInstallFvInfoPpi ( 476 IN CONST EFI_GUID *FvFormat, OPTIONAL 477 IN CONST VOID *FvInfo, 478 IN UINT32 FvInfoSize, 479 IN CONST EFI_GUID *ParentFvName, OPTIONAL 480 IN CONST EFI_GUID *ParentFileName OPTIONAL 481 ); 482 483 /** 484 Install a EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI instance so the PEI Core will be notified about a new firmware volume. 485 486 This function allocates, initializes, and installs a new EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI using 487 the parameters passed in to initialize the fields of the EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI instance. 488 If the resources can not be allocated for EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI, then ASSERT(). 489 If the EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI can not be installed, then ASSERT(). 490 491 @param FvFormat Unique identifier of the format of the memory-mapped 492 firmware volume. This parameter is optional and 493 may be NULL. If NULL is specified, the 494 EFI_FIRMWARE_FILE_SYSTEM2_GUID format is assumed. 495 @param FvInfo Points to a buffer which allows the 496 EFI_PEI_FIRMWARE_VOLUME_PPI to process the volume. 497 The format of this buffer is specific to the FvFormat. 498 For memory-mapped firmware volumes, this typically 499 points to the first byte of the firmware volume. 500 @param FvInfoSize The size, in bytes, of FvInfo. For memory-mapped 501 firmware volumes, this is typically the size of 502 the firmware volume. 503 @param ParentFvName If the new firmware volume originated from a file 504 in a different firmware volume, then this parameter 505 specifies the GUID name of the originating firmware 506 volume. Otherwise, this parameter must be NULL. 507 @param ParentFileName If the new firmware volume originated from a file 508 in a different firmware volume, then this parameter 509 specifies the GUID file name of the originating 510 firmware file. Otherwise, this parameter must be NULL. 511 @param AuthenticationStatus Authentication Status 512 **/ 513 VOID 514 EFIAPI 515 PeiServicesInstallFvInfo2Ppi ( 516 IN CONST EFI_GUID *FvFormat, OPTIONAL 517 IN CONST VOID *FvInfo, 518 IN UINT32 FvInfoSize, 519 IN CONST EFI_GUID *ParentFvName, OPTIONAL 520 IN CONST EFI_GUID *ParentFileName, OPTIONAL 521 IN UINT32 AuthenticationStatus 522 ); 523 524 #endif 525