MdePkg/Library/PeiServicesLib/PeiServicesLib.c

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