MdePkg/Include/Library/PeiCoreLib.h

   1 /** @file
   2         PEI Core Library implementation
   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:    PeiCoreLib.h
  14
  15 **/
  16
  17 #ifndef __PEI_CORE_LIB_H__
  18 #define __PEI_CORE_LIB_H__
  19
  20 /**
  21         This service enables a given PEIM to register an interface into the PEI Foundation.
  22
  23         @param  PpiList A pointer to the list of interfaces that the caller shall install.
  24
  25         @retval EFI_SUCCESS The interface was successfully installed.
  26         @retval EFI_INVALID_PARAMETER The PpiList pointer is NULL.
  27         @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have
  28         the EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
  29         @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
  30
  31 **/
  32 EFI_STATUS
  33 EFIAPI
  34 PeiCoreInstallPpi (
  35   IN EFI_PEI_PPI_DESCRIPTOR           *PpiList
  36   )
  37 ;
  38
  39 /**
  40         This service enables PEIMs to replace an entry in the PPI database with an alternate entry.
  41
  42         @param  OldPpi Pointer to the old PEI PPI Descriptors.
  43         @param  NewPpi Pointer to the new PEI PPI Descriptors.
  44
  45         @retval EFI_SUCCESS The interface was successfully installed.
  46         @retval EFI_INVALID_PARAMETER The OldPpi or NewPpi is NULL.
  47         @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have
  48         the EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
  49         @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
  50         @retval EFI_NOT_FOUND The PPI for which the reinstallation was requested has not been installed.
  51
  52 **/
  53 EFI_STATUS
  54 EFIAPI
  55 PeiCoreReinstallPpi (
  56   IN EFI_PEI_PPI_DESCRIPTOR           *OldPpi,
  57   IN EFI_PEI_PPI_DESCRIPTOR           *NewPpi
  58   )
  59 ;
  60
  61 /**
  62         This service enables PEIMs to discover a given instance of an interface.
  63
  64         @param  Guid A pointer to the GUID whose corresponding interface needs to be found.
  65         @param  Instance The N-th instance of the interface that is required.
  66         @param  PpiDescriptor A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR.
  67         @param  Ppi A pointer to the instance of the interface.
  68
  69         @retval EFI_SUCCESS The interface was successfully returned.
  70         @retval EFI_NOT_FOUND The PPI descriptor is not found in the database.
  71
  72 **/
  73 EFI_STATUS
  74 EFIAPI
  75 PeiCoreLocatePpi (
  76   IN EFI_GUID                         *Guid,
  77   IN UINTN                            Instance,
  78   IN OUT EFI_PEI_PPI_DESCRIPTOR       **PpiDescriptor,
  79   IN OUT VOID                         **Ppi
  80   )
  81 ;
  82
  83 /**
  84         This service enables PEIMs to register a given service to be invoked
  85         when another service is installed or reinstalled.
  86
  87         @param  NotifyList A pointer to the list of notification interfaces that the caller shall install.
  88
  89         @retval EFI_SUCCESS The interface was successfully installed.
  90         @retval EFI_INVALID_PARAMETER The NotifyList pointer is NULL.
  91         @retval EFI_INVALID_PARAMETER Any of the PEI notify descriptors in the list do not have
  92         the EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field.
  93         @retval EFI_OUT_OF_RESOURCES There is no additional space in the PPI database.
  94
  95 **/
  96 EFI_STATUS
  97 EFIAPI
  98 PeiCoreNotifyPpi (
  99   IN EFI_PEI_NOTIFY_DESCRIPTOR        *NotifyList
 100   )
 101 ;
 102
 103 /**
 104         This service enables PEIMs to ascertain the present value of the boot mode.
 105
 106         @param  BootMode A pointer to contain the value of the boot mode.
 107
 108         @retval EFI_SUCCESS The boot mode was returned successfully.
 109         @retval EFI_INVALID_PARAMETER BootMode is NULL.
 110
 111 **/
 112 EFI_STATUS
 113 EFIAPI
 114 PeiCoreGetBootMode (
 115   IN OUT EFI_BOOT_MODE                *BootMode
 116   )
 117 ;
 118
 119 /**
 120         This service enables PEIMs to update the boot mode variable.
 121
 122         @param  BootMode The value of the boot mode to set.
 123
 124         @retval EFI_SUCCESS The value was successfully updated
 125
 126 **/
 127 EFI_STATUS
 128 EFIAPI
 129 PeiCoreSetBootMode (
 130   IN EFI_BOOT_MODE                    BootMode
 131   )
 132 ;
 133
 134 /**
 135         This service enables a PEIM to ascertain the address of the list of HOBs in memory.
 136
 137         @param  HobList A pointer to the list of HOBs that the PEI Foundation will initialize.
 138
 139         @retval EFI_SUCCESS The list was successfully returned.
 140         @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published.
 141
 142 **/
 143 EFI_STATUS
 144 EFIAPI
 145 PeiCoreGetHobList (
 146   IN OUT VOID                         **HobList
 147   )
 148 ;
 149
 150 /**
 151         This service enables PEIMs to create various types of HOBs.
 152
 153         @param  Type The type of HOB to be installed.
 154         @param  Length The length of the HOB to be added.
 155         @param  Hob The address of a pointer that will contain the HOB header.
 156
 157         @retval EFI_SUCCESS The HOB was successfully created.
 158         @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation.
 159
 160 **/
 161 EFI_STATUS
 162 EFIAPI
 163 PeiCoreCreateHob (
 164   IN UINT16                           Type,
 165   IN UINT16                           Length,
 166   IN OUT VOID                         **Hob
 167   )
 168 ;
 169
 170 /**
 171         This service enables PEIMs to discover additional firmware volumes.
 172
 173         @param  Instance This instance of the firmware volume to find.
 174         The value 0 is the Boot Firmware Volume (BFV).
 175         @param  FwVolHeader Pointer to the firmware volume header of the volume to return.
 176
 177         @retval EFI_SUCCESS The volume was found.
 178         @retval EFI_NOT_FOUND The volume was not found.
 179         @retval EFI_INVALID_PARAMETER FwVolHeader is NULL.
 180
 181 **/
 182 EFI_STATUS
 183 EFIAPI
 184 PeiCoreFfsFindNextVolume (
 185   IN UINTN                            Instance,
 186   IN OUT EFI_FIRMWARE_VOLUME_HEADER   **FwVolHeader
 187   )
 188 ;
 189
 190 /**
 191         This service enables PEIMs to discover additional firmware files.
 192
 193         @param  SearchType A filter to find files only of this type.
 194         @param  FwVolHeader Pointer to the firmware volume header of the volume to search.
 195         This parameter must point to a valid FFS volume.
 196         @param  FileHeader Pointer to the current file from which to begin searching.
 197
 198         @retval EFI_SUCCESS The file was found.
 199         @retval EFI_NOT_FOUND The file was not found.
 200         @retval EFI_NOT_FOUND The header checksum was not zero.
 201
 202 **/
 203 EFI_STATUS
 204 EFIAPI
 205 PeiCoreFfsFindNextFile (
 206   IN EFI_FV_FILETYPE                  SearchType,
 207   IN EFI_FIRMWARE_VOLUME_HEADER       *FwVolHeader,
 208   IN OUT EFI_FFS_FILE_HEADER          **FileHeader
 209   )
 210 ;
 211
 212 /**
 213         This service enables PEIMs to discover sections of a given type within a valid FFS file.
 214
 215         @param  SearchType The value of the section type to find.
 216         @param  FfsFileHeader A pointer to the file header that contains the set of sections to be searched.
 217         @param  SectionData A pointer to the discovered section, if successful.
 218
 219         @retval EFI_SUCCESS The section was found.
 220         @retval EFI_NOT_FOUND The section was not found.
 221
 222 **/
 223 EFI_STATUS
 224 EFIAPI
 225 PeiCoreFfsFindSectionData (
 226   IN EFI_SECTION_TYPE                 SectionType,
 227   IN EFI_FFS_FILE_HEADER              *FfsFileHeader,
 228   IN OUT VOID                         **SectionData
 229   )
 230 ;
 231
 232 /**
 233         This service enables PEIMs to register the permanent memory configuration
 234         that has been initialized with the PEI Foundation.
 235
 236         @param  MemoryBegin The value of a region of installed memory.
 237         @param  MemoryLength The corresponding length of a region of installed memory.
 238
 239         @retval EFI_SUCCESS The region was successfully installed in a HOB.
 240         @retval EFI_INVALID_PARAMETER MemoryBegin and MemoryLength are illegal for this system.
 241         @retval EFI_OUT_OF_RESOURCES There is no additional space for HOB creation.
 242
 243 **/
 244 EFI_STATUS
 245 EFIAPI
 246 PeiCoreInstallPeiMemory (
 247   IN EFI_PHYSICAL_ADDRESS             MemoryBegin,
 248   IN UINT64                           MemoryLength
 249   )
 250 ;
 251
 252 /**
 253         This service enables PEIMs to allocate memory after the permanent memory has been installed by a PEIM.
 254
 255         @param  MemoryType Type of memory to allocate.
 256         @param  Pages Number of pages to allocate.
 257         @param  Memory Pointer of memory allocated.
 258
 259         @retval EFI_SUCCESS The memory range was successfully allocated.
 260         @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages.
 261         @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available.
 262         @retval EFI_OUT_OF_RESOURCES The pages could not be allocated.
 263
 264 **/
 265 EFI_STATUS
 266 EFIAPI
 267 PeiCoreAllocatePages (
 268   IN EFI_MEMORY_TYPE                  MemoryType,
 269   IN UINTN                            Pages,
 270   IN OUT EFI_PHYSICAL_ADDRESS         *Memory
 271   )
 272 ;
 273
 274 /**
 275         This service allocates memory from the Hand-Off Block (HOB) heap.
 276
 277         @param  Size The number of bytes to allocate from the pool.
 278         @param  Buffer If the call succeeds, a pointer to a pointer to the allocated buffer;
 279         undefined otherwise.
 280
 281         @retval EFI_SUCCESS The allocation was successful
 282         @retval EFI_OUT_OF_RESOURCES There is not enough heap to allocate the requested size.
 283
 284 **/
 285 EFI_STATUS
 286 EFIAPI
 287 PeiCoreAllocatePool (
 288   IN UINTN                            Size,
 289   OUT VOID                            **Buffer
 290   )
 291 ;
 292
 293 /**
 294         This service resets the entire platform, including all processors and devices, and reboots the system.
 295
 296         @retval EFI_NOT_AVAILABLE_YET The service has not been installed yet.
 297
 298 **/
 299 EFI_STATUS
 300 EFIAPI
 301 PeiCoreResetSystem (
 302   VOID
 303   )
 304 ;
 305
 306 #endif