EdkCompatibilityPkg/Foundation/Library/EdkIIGlueLib/Include/Library/EdkIIGluePeiServicesLib.h

   1 /*++
   2
   3 Copyright (c) 2004 - 2006, Intel Corporation. All rights reserved.<BR>
   4 This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12
  13 Module Name:
  14
  15   EdkIIGluePeiServicesLib.h
  16
  17 Abstract:
  18
  19   Public header file for PEI Services Lib
  20
  21 --*/
  22
  23 #ifndef __EDKII_GLUE_PEI_SERVICES_LIB_H__
  24 #define __EDKII_GLUE_PEI_SERVICES_LIB_H__
  25
  26 //
  27 // To avoid macro expansion issue when the parameter list has #if #endif.
  28 //
  29 #define PeiServicesLocatePpi   GluePeiServicesLocatePpi
  30
  31 /**
  32   This service enables a given PEIM to register an interface into the PEI Foundation.
  33
  34   @param  PpiList               A pointer to the list of interfaces that the caller shall install.
  35
  36   @retval EFI_SUCCESS           The interface was successfully installed.
  37   @retval EFI_INVALID_PARAMETER The PpiList pointer is NULL.
  38   @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the
  39                                 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
  40   @retval EFI_OUT_OF_RESOURCES  There is no additional space in the PPI database.
  41
  42 **/
  43 EFI_STATUS
  44 EFIAPI
  45 PeiServicesInstallPpi (
  46   IN EFI_PEI_PPI_DESCRIPTOR     *PpiList
  47   );
  48
  49 /**
  50   This service enables PEIMs to replace an entry in the PPI database with an alternate entry.
  51
  52   @param  OldPpi                Pointer to the old PEI PPI Descriptors.
  53   @param  NewPpi                Pointer to the new PEI PPI Descriptors.
  54
  55   @retval EFI_SUCCESS           The interface was successfully installed.
  56   @retval EFI_INVALID_PARAMETER The OldPpi or NewPpi is NULL.
  57   @retval EFI_INVALID_PARAMETER Any of the PEI PPI descriptors in the list do not have the
  58                                 EFI_PEI_PPI_DESCRIPTOR_PPI bit set in the Flags field.
  59   @retval EFI_OUT_OF_RESOURCES  There is no additional space in the PPI database.
  60   @retval EFI_NOT_FOUND         The PPI for which the reinstallation was requested has not been
  61                                 installed.
  62
  63 **/
  64 EFI_STATUS
  65 EFIAPI
  66 PeiServicesReInstallPpi (
  67   IN EFI_PEI_PPI_DESCRIPTOR     *OldPpi,
  68   IN EFI_PEI_PPI_DESCRIPTOR     *NewPpi
  69   );
  70
  71 /**
  72   This service enables PEIMs to discover a given instance of an interface.
  73
  74   @param  Guid                  A pointer to the GUID whose corresponding interface needs to be
  75                                 found.
  76   @param  Instance              The N-th instance of the interface that is required.
  77   @param  PpiDescriptor         A pointer to instance of the EFI_PEI_PPI_DESCRIPTOR.
  78   @param  Ppi                   A pointer to the instance of the interface.
  79
  80   @retval EFI_SUCCESS           The interface was successfully returned.
  81   @retval EFI_NOT_FOUND         The PPI descriptor is not found in the database.
  82
  83 **/
  84 EFI_STATUS
  85 EFIAPI
  86 PeiServicesLocatePpi (
  87   IN EFI_GUID                   *Guid,
  88   IN UINTN                      Instance,
  89   IN OUT EFI_PEI_PPI_DESCRIPTOR **PpiDescriptor,
  90   IN OUT VOID                   **Ppi
  91   );
  92
  93 /**
  94   This service enables PEIMs to register a given service to be invoked when another service is
  95   installed or reinstalled.
  96
  97   @param  NotifyList            A pointer to the list of notification interfaces that the caller
  98                                 shall install.
  99
 100   @retval EFI_SUCCESS           The interface was successfully installed.
 101   @retval EFI_INVALID_PARAMETER The NotifyList pointer is NULL.
 102   @retval EFI_INVALID_PARAMETER Any of the PEI notify descriptors in the list do not have the
 103                                 EFI_PEI_PPI_DESCRIPTOR_NOTIFY_TYPES bit set in the Flags field.
 104   @retval EFI_OUT_OF_RESOURCES  There is no additional space in the PPI database.
 105
 106 **/
 107 EFI_STATUS
 108 EFIAPI
 109 PeiServicesNotifyPpi (
 110   IN EFI_PEI_NOTIFY_DESCRIPTOR  *NotifyList
 111   );
 112
 113 /**
 114   This service enables PEIMs to ascertain the present value of the boot mode.
 115
 116   @param  BootMode              A pointer to contain the value of the boot mode.
 117
 118   @retval EFI_SUCCESS           The boot mode was returned successfully.
 119   @retval EFI_INVALID_PARAMETER BootMode is NULL.
 120
 121 **/
 122 EFI_STATUS
 123 EFIAPI
 124 PeiServicesGetBootMode (
 125   IN OUT EFI_BOOT_MODE          *BootMode
 126   );
 127
 128 /**
 129   This service enables PEIMs to update the boot mode variable.
 130
 131   @param  BootMode              The value of the boot mode to set.
 132
 133   @retval EFI_SUCCESS           The value was successfully updated
 134
 135 **/
 136 EFI_STATUS
 137 EFIAPI
 138 PeiServicesSetBootMode (
 139   IN EFI_BOOT_MODE              BootMode
 140   );
 141
 142 /**
 143   This service enables a PEIM to ascertain the address of the list of HOBs in memory.
 144
 145   @param  HobList               A pointer to the list of HOBs that the PEI Foundation will initialize.
 146
 147   @retval EFI_SUCCESS           The list was successfully returned.
 148   @retval EFI_NOT_AVAILABLE_YET The HOB list is not yet published.
 149
 150 **/
 151 EFI_STATUS
 152 EFIAPI
 153 PeiServicesGetHobList (
 154   IN OUT VOID                   **HobList
 155   );
 156
 157 /**
 158   This service enables PEIMs to create various types of HOBs.
 159
 160   @param  Type                  The type of HOB to be installed.
 161   @param  Length                The length of the HOB to be added.
 162   @param  Hob                   The address of a pointer that will contain the HOB header.
 163
 164   @retval EFI_SUCCESS           The HOB was successfully created.
 165   @retval EFI_OUT_OF_RESOURCES  There is no additional space for HOB creation.
 166
 167 **/
 168 EFI_STATUS
 169 EFIAPI
 170 PeiServicesCreateHob (
 171   IN UINT16                     Type,
 172   IN UINT16                     Length,
 173   IN OUT VOID                   **Hob
 174   );
 175
 176 #if (PI_SPECIFICATION_VERSION < 0x00010000)
 177 /**
 178   This service enables PEIMs to discover additional firmware volumes.
 179
 180   @param  Instance              This instance of the firmware volume to find.  The value 0 is the
 181                                 Boot Firmware Volume (BFV).
 182   @param  FwVolHeader           Pointer to the firmware volume header of the volume to return.
 183
 184   @retval EFI_SUCCESS           The volume was found.
 185   @retval EFI_NOT_FOUND         The volume was not found.
 186   @retval EFI_INVALID_PARAMETER FwVolHeader is NULL.
 187
 188 **/
 189 EFI_STATUS
 190 EFIAPI
 191 PeiServicesFfsFindNextVolume (
 192   IN UINTN                          Instance,
 193   IN OUT EFI_FIRMWARE_VOLUME_HEADER **FwVolHeader
 194   );
 195
 196 /**
 197   This service enables PEIMs to discover additional firmware files.
 198
 199   @param  SearchType            A filter to find files only of this type.
 200   @param  FwVolHeader           Pointer to the firmware volume header of the volume to search.
 201                                 This parameter must point to a valid FFS volume.
 202   @param  FileHeader            Pointer to the current file from which to begin searching.
 203
 204   @retval EFI_SUCCESS           The file was found.
 205   @retval EFI_NOT_FOUND         The file was not found.
 206   @retval EFI_NOT_FOUND         The header checksum was not zero.
 207
 208 **/
 209 EFI_STATUS
 210 EFIAPI
 211 PeiServicesFfsFindNextFile (
 212   IN EFI_FV_FILETYPE            SearchType,
 213   IN EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader,
 214   IN OUT EFI_FFS_FILE_HEADER    **FileHeader
 215   );
 216
 217 /**
 218   This service enables PEIMs to discover sections of a given type within a valid FFS file.
 219
 220   @param  SearchType            The value of the section type to find.
 221   @param  FfsFileHeader         A pointer to the file header that contains the set of sections to
 222                                 be searched.
 223   @param  SectionData           A pointer to the discovered section, if successful.
 224
 225   @retval EFI_SUCCESS           The section was found.
 226   @retval EFI_NOT_FOUND         The section was not found.
 227
 228 **/
 229 EFI_STATUS
 230 EFIAPI
 231 PeiServicesFfsFindSectionData (
 232   IN EFI_SECTION_TYPE           SectionType,
 233   IN EFI_FFS_FILE_HEADER        *FfsFileHeader,
 234   IN OUT VOID                   **SectionData
 235   );
 236 #endif
 237
 238 /**
 239   This service enables PEIMs to register the permanent memory configuration
 240   that has been initialized with the PEI Foundation.
 241
 242   @param  MemoryBegin           The value of a region of installed memory.
 243   @param  MemoryLength          The corresponding length of a region of installed memory.
 244
 245   @retval EFI_SUCCESS           The region was successfully installed in a HOB.
 246   @retval EFI_INVALID_PARAMETER MemoryBegin and MemoryLength are illegal for this system.
 247   @retval EFI_OUT_OF_RESOURCES  There is no additional space for HOB creation.
 248
 249 **/
 250 EFI_STATUS
 251 EFIAPI
 252 PeiServicesInstallPeiMemory (
 253   IN EFI_PHYSICAL_ADDRESS       MemoryBegin,
 254   IN UINT64                     MemoryLength
 255   );
 256
 257 /**
 258   This service enables PEIMs to allocate memory after the permanent memory has been installed by a
 259   PEIM.
 260
 261   @param  MemoryType            Type of memory to allocate.
 262   @param  Pages                 Number of pages to allocate.
 263   @param  Memory                Pointer of memory allocated.
 264
 265   @retval EFI_SUCCESS           The memory range was successfully allocated.
 266   @retval EFI_INVALID_PARAMETER Type is not equal to AllocateAnyPages.
 267   @retval EFI_NOT_AVAILABLE_YET Called with permanent memory not available.
 268   @retval EFI_OUT_OF_RESOURCES  The pages could not be allocated.
 269
 270 **/
 271 EFI_STATUS
 272 EFIAPI
 273 PeiServicesAllocatePages (
 274   IN EFI_MEMORY_TYPE            MemoryType,
 275   IN UINTN                      Pages,
 276   IN OUT EFI_PHYSICAL_ADDRESS   *Memory
 277   );
 278
 279 /**
 280   This service allocates memory from the Hand-Off Block (HOB) heap.
 281
 282   @param  Size                  The number of bytes to allocate from the pool.
 283   @param  Buffer                If the call succeeds, a pointer to a pointer to the allocate
 284                                 buffer; undefined otherwise.
 285
 286   @retval EFI_SUCCESS           The allocation was successful
 287   @retval EFI_OUT_OF_RESOURCES  There is not enough heap to allocate the requested size.
 288
 289 **/
 290 EFI_STATUS
 291 EFIAPI
 292 PeiServicesAllocatePool (
 293   IN UINTN                      Size,
 294   OUT VOID                      **Buffer
 295   );
 296
 297 /**
 298   This service resets the entire platform, including all processors and devices, and reboots the
 299   system.
 300
 301   @retval EFI_NOT_AVAILABLE_YET The service has not been installed yet.
 302
 303 **/
 304 EFI_STATUS
 305 EFIAPI
 306 PeiServicesResetSystem (
 307   VOID
 308   );
 309
 310 /**
 311   PCI read-modify-write operations.
 312
 313   PIWG's PI specification replaces Inte's EFI Specification 1.10.
 314   EFI_PEI_PCI_CFG_PPI defined in Inte's EFI Specification 1.10 is replaced by
 315   EFI_PEI_PCI_CFG2_PPI in PI 1.0. "Modify" function  in these two PPI are not
 316   compatibile with each other.
 317
 318   For Framework code that make the following call:
 319       PciCfg->Modify (
 320                        PeiServices,
 321                        PciCfg,
 322                        Width,
 323                        Address,
 324                        SetBits,
 325                        ClearBits
 326                        );
 327    it will be updated to the following code which call this library API:
 328       PeiLibPciCfgModify (
 329           PeiServices,
 330           PciCfg,
 331           Width,
 332           Address,
 333           SetBits,
 334           ClearBits
 335           );
 336
 337   @param  PeiServices     An indirect pointer to the PEI Services Table
 338                           published by the PEI Foundation.
 339   @param  PciCfg          A pointer to the this pointer of EFI_PEI_PCI_CFG_PPI.
 340                           This parameter is unused as a place holder to make
 341                           the parameter list identical to PEI_PCI_CFG_PPI_RW.
 342   @param  Width           The width of the access. Enumerated in bytes. Type
 343                           EFI_PEI_PCI_CFG_PPI_WIDTH is defined in Read().
 344   @param  Address         The physical address of the access.
 345   @param  SetBits         Points to value to bitwise-OR with the read configuration value.
 346                           The size of the value is determined by Width.
 347   @param  ClearBits       Points to the value to negate and bitwise-AND with the read configuration value.
 348                           The size of the value is determined by Width.
 349
 350   @retval EFI_SUCCESS     The function completed successfully.
 351   @retval EFI_DEVICE_ERROR There was a problem with the transaction.
 352 **/
 353 EFI_STATUS
 354 EFIAPI
 355 PeiLibPciCfgModify (
 356   IN EFI_PEI_SERVICES         **PeiServices,
 357   IN PEI_PCI_CFG_PPI          *PciCfg,
 358   IN PEI_PCI_CFG_PPI_WIDTH    Width,
 359   IN UINT64                   Address,
 360   IN UINTN                    SetBits,
 361   IN UINTN                    ClearBits
 362   )
 363 ;
 364
 365 #endif