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