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