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