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