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