MdePkg/Include/Ppi/FirmwareVolume.h

   1 /** @file
   2   This file provides functions for accessing a memory-mapped firmware volume of a specific format.
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8   This PPI is from PI Version 1.0 errata.
   9
  10 **/
  11
  12 #ifndef __FIRMWARE_VOLUME_PPI_H__
  13 #define __FIRMWARE_VOLUME_PPI_H__
  14
  15 ///
  16 /// The GUID for this PPI is the same as the firmware volume format GUID.
  17 /// The FV format can be EFI_FIRMWARE_FILE_SYSTEM2_GUID or the GUID for a user-defined
  18 /// format. The EFI_FIRMWARE_FILE_SYSTEM2_GUID is the PI Firmware Volume format.
  19 ///
  20 typedef struct _EFI_PEI_FIRMWARE_VOLUME_PPI EFI_PEI_FIRMWARE_VOLUME_PPI;
  21
  22 /**
  23   Process a firmware volume and create a volume handle.
  24
  25   Create a volume handle from the information in the buffer. For
  26   memory-mapped firmware volumes, Buffer and BufferSize refer to
  27   the start of the firmware volume and the firmware volume size.
  28   For non memory-mapped firmware volumes, this points to a
  29   buffer which contains the necessary information for creating
  30   the firmware volume handle. Normally, these values are derived
  31   from the EFI_FIRMWARE_VOLUME_INFO_PPI.
  32
  33
  34   @param This                   Points to this instance of the
  35                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
  36   @param Buffer                 Points to the start of the buffer.
  37   @param BufferSize             Size of the buffer.
  38   @param FvHandle               Points to the returned firmware volume
  39                                 handle. The firmware volume handle must
  40                                 be unique within the system.
  41
  42   @retval EFI_SUCCESS           Firmware volume handle created.
  43   @retval EFI_VOLUME_CORRUPTED  Volume was corrupt.
  44
  45 **/
  46 typedef
  47 EFI_STATUS
  48 (EFIAPI *EFI_PEI_FV_PROCESS_FV)(
  49   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,
  50   IN  VOID                               *Buffer,
  51   IN  UINTN                              BufferSize,
  52   OUT EFI_PEI_FV_HANDLE                  *FvHandle
  53   );
  54
  55 /**
  56   Finds the next file of the specified type.
  57
  58   This service enables PEI modules to discover additional firmware files.
  59   The FileHandle must be unique within the system.
  60
  61   @param This           Points to this instance of the
  62                         EFI_PEI_FIRMWARE_VOLUME_PPI.
  63   @param SearchType     A filter to find only files of this type. Type
  64                         EFI_FV_FILETYPE_ALL causes no filtering to be
  65                         done.
  66   @param FvHandle       Handle of firmware volume in which to
  67                         search.
  68   @param FileHandle     Points to the current handle from which to
  69                         begin searching or NULL to start at the
  70                         beginning of the firmware volume. Updated
  71                         upon return to reflect the file found.
  72
  73   @retval EFI_SUCCESS   The file was found.
  74   @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.
  75
  76 **/
  77 typedef
  78 EFI_STATUS
  79 (EFIAPI *EFI_PEI_FV_FIND_FILE_TYPE)(
  80   IN     CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
  81   IN     EFI_FV_FILETYPE                     SearchType,
  82   IN     EFI_PEI_FV_HANDLE                   FvHandle,
  83   IN OUT EFI_PEI_FILE_HANDLE                 *FileHandle
  84   );
  85
  86 /**
  87   Find a file within a volume by its name.
  88
  89   This service searches for files with a specific name, within
  90   either the specified firmware volume or all firmware volumes.
  91
  92   @param This                   Points to this instance of the
  93                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
  94   @param FileName               A pointer to the name of the file to find
  95                                 within the firmware volume.
  96   @param FvHandle               Upon entry, the pointer to the firmware
  97                                 volume to search or NULL if all firmware
  98                                 volumes should be searched. Upon exit, the
  99                                 actual firmware volume in which the file was
 100                                 found.
 101   @param FileHandle             Upon exit, points to the found file's
 102                                 handle or NULL if it could not be found.
 103
 104   @retval EFI_SUCCESS           File was found.
 105   @retval EFI_NOT_FOUND         File was not found.
 106   @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or
 107                                 FileName was NULL.
 108
 109
 110 **/
 111 typedef
 112 EFI_STATUS
 113 (EFIAPI *EFI_PEI_FV_FIND_FILE_NAME)(
 114   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,
 115   IN  CONST  EFI_GUID                    *FileName,
 116   IN  EFI_PEI_FV_HANDLE                  *FvHandle,
 117   OUT EFI_PEI_FILE_HANDLE                *FileHandle
 118   );
 119
 120 /**
 121   Returns information about a specific file.
 122
 123   This function returns information about a specific
 124   file, including its file name, type, attributes, starting
 125   address and size.
 126
 127   @param This                     Points to this instance of the
 128                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 129   @param FileHandle               Handle of the file.
 130   @param FileInfo                 Upon exit, points to the file's
 131                                   information.
 132
 133   @retval EFI_SUCCESS             File information returned.
 134   @retval EFI_INVALID_PARAMETER   If FileHandle does not
 135                                   represent a valid file.
 136   @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.
 137
 138 **/
 139 typedef
 140 EFI_STATUS
 141 (EFIAPI *EFI_PEI_FV_GET_FILE_INFO)(
 142   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 143   IN  EFI_PEI_FILE_HANDLE                 FileHandle,
 144   OUT EFI_FV_FILE_INFO                    *FileInfo
 145   );
 146
 147 /**
 148   Returns information about a specific file.
 149
 150   This function returns information about a specific
 151   file, including its file name, type, attributes, starting
 152   address, size and authentication status.
 153
 154   @param This                     Points to this instance of the
 155                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 156   @param FileHandle               Handle of the file.
 157   @param FileInfo                 Upon exit, points to the file's
 158                                   information.
 159
 160   @retval EFI_SUCCESS             File information returned.
 161   @retval EFI_INVALID_PARAMETER   If FileHandle does not
 162                                   represent a valid file.
 163   @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.
 164
 165 **/
 166 typedef
 167 EFI_STATUS
 168 (EFIAPI *EFI_PEI_FV_GET_FILE_INFO2)(
 169   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 170   IN  EFI_PEI_FILE_HANDLE                 FileHandle,
 171   OUT EFI_FV_FILE_INFO2                   *FileInfo
 172   );
 173
 174 /**
 175   This function returns information about the firmware volume.
 176
 177   @param This                     Points to this instance of the
 178                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 179   @param FvHandle                 Handle to the firmware handle.
 180   @param VolumeInfo               Points to the returned firmware volume
 181                                   information.
 182
 183   @retval EFI_SUCCESS             Information returned successfully.
 184   @retval EFI_INVALID_PARAMETER   FvHandle does not indicate a valid
 185                                   firmware volume or VolumeInfo is NULL.
 186
 187 **/
 188 typedef
 189 EFI_STATUS
 190 (EFIAPI *EFI_PEI_FV_GET_INFO)(
 191   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 192   IN  EFI_PEI_FV_HANDLE                    FvHandle,
 193   OUT EFI_FV_INFO                          *VolumeInfo
 194   );
 195
 196 /**
 197   Find the next matching section in the firmware file.
 198
 199   This service enables PEI modules to discover sections
 200   of a given type within a valid file.
 201
 202   @param This             Points to this instance of the
 203                           EFI_PEI_FIRMWARE_VOLUME_PPI.
 204   @param SearchType       A filter to find only sections of this
 205                           type.
 206   @param FileHandle       Handle of firmware file in which to
 207                           search.
 208   @param SectionData      Updated upon  return to point to the
 209                           section found.
 210
 211   @retval EFI_SUCCESS     Section was found.
 212   @retval EFI_NOT_FOUND   Section of the specified type was not
 213                           found. SectionData contains NULL.
 214 **/
 215 typedef
 216 EFI_STATUS
 217 (EFIAPI *EFI_PEI_FV_FIND_SECTION)(
 218   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI    *This,
 219   IN  EFI_SECTION_TYPE                     SearchType,
 220   IN  EFI_PEI_FILE_HANDLE                  FileHandle,
 221   OUT VOID                                 **SectionData
 222   );
 223
 224 /**
 225   Find the next matching section in the firmware file.
 226
 227   This service enables PEI modules to discover sections
 228   of a given instance and type within a valid file.
 229
 230   @param This                   Points to this instance of the
 231                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
 232   @param SearchType             A filter to find only sections of this
 233                                 type.
 234   @param SearchInstance         A filter to find the specific instance
 235                                 of sections.
 236   @param FileHandle             Handle of firmware file in which to
 237                                 search.
 238   @param SectionData            Updated upon return to point to the
 239                                 section found.
 240   @param AuthenticationStatus   Updated upon return to point to the
 241                                 authentication status for this section.
 242
 243   @retval EFI_SUCCESS     Section was found.
 244   @retval EFI_NOT_FOUND   Section of the specified type was not
 245                           found. SectionData contains NULL.
 246 **/
 247 typedef
 248 EFI_STATUS
 249 (EFIAPI *EFI_PEI_FV_FIND_SECTION2)(
 250   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI    *This,
 251   IN  EFI_SECTION_TYPE                     SearchType,
 252   IN  UINTN                                SearchInstance,
 253   IN  EFI_PEI_FILE_HANDLE                  FileHandle,
 254   OUT VOID                                 **SectionData,
 255   OUT UINT32                               *AuthenticationStatus
 256   );
 257
 258 #define EFI_PEI_FIRMWARE_VOLUME_PPI_SIGNATURE  SIGNATURE_32 ('P', 'F', 'V', 'P')
 259 #define EFI_PEI_FIRMWARE_VOLUME_PPI_REVISION   0x00010030
 260
 261 ///
 262 /// This PPI provides functions for accessing a memory-mapped firmware volume of a specific format.
 263 ///
 264 struct _EFI_PEI_FIRMWARE_VOLUME_PPI {
 265   EFI_PEI_FV_PROCESS_FV        ProcessVolume;
 266   EFI_PEI_FV_FIND_FILE_TYPE    FindFileByType;
 267   EFI_PEI_FV_FIND_FILE_NAME    FindFileByName;
 268   EFI_PEI_FV_GET_FILE_INFO     GetFileInfo;
 269   EFI_PEI_FV_GET_INFO          GetVolumeInfo;
 270   EFI_PEI_FV_FIND_SECTION      FindSectionByType;
 271   EFI_PEI_FV_GET_FILE_INFO2    GetFileInfo2;
 272   EFI_PEI_FV_FIND_SECTION2     FindSectionByType2;
 273   ///
 274   /// Signature is used to keep backward-compatibility, set to {'P','F','V','P'}.
 275   ///
 276   UINT32                       Signature;
 277   ///
 278   /// Revision for further extension.
 279   ///
 280   UINT32                       Revision;
 281 };
 282
 283 extern EFI_GUID  gEfiPeiFirmwareVolumePpiGuid;
 284
 285 #endif