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