MdeModulePkg/Core/Pei/FwVol/FwVol.h

   1 /** @file
   2   The internal header file for firmware volume related definitions.
   3
   4 Copyright (c) 2009 - 2011, 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 **/
  14
  15 #ifndef _FWVOL_H_
  16 #define _FWVOL_H_
  17
  18 #include "PeiMain.h"
  19
  20 #define GET_OCCUPIED_SIZE(ActualSize, Alignment) \
  21   ((ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1)))
  22
  23
  24 #define PEI_FW_VOL_SIGNATURE  SIGNATURE_32('P','F','W','V')
  25
  26 typedef struct {
  27   UINTN                         Signature;
  28   BOOLEAN                       IsFfs3Fv;
  29   EFI_PEI_FIRMWARE_VOLUME_PPI   Fv;
  30 } PEI_FW_VOL_INSTANCE;
  31
  32 #define PEI_FW_VOL_INSTANCE_FROM_FV_THIS(a) \
  33   CR(a, PEI_FW_VOL_INSTANCE, Fv, PEI_FW_VOL_SIGNATURE)
  34
  35
  36 /**
  37   Process a firmware volume and create a volume handle.
  38
  39   Create a volume handle from the information in the buffer. For
  40   memory-mapped firmware volumes, Buffer and BufferSize refer to
  41   the start of the firmware volume and the firmware volume size.
  42   For non memory-mapped firmware volumes, this points to a
  43   buffer which contains the necessary information for creating
  44   the firmware volume handle. Normally, these values are derived
  45   from the EFI_FIRMWARE_VOLUME_INFO_PPI.
  46
  47
  48   @param This                   Points to this instance of the
  49                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
  50   @param Buffer                 Points to the start of the buffer.
  51   @param BufferSize             Size of the buffer.
  52   @param FvHandle               Points to the returned firmware volume
  53                                 handle. The firmware volume handle must
  54                                 be unique within the system.
  55
  56   @retval EFI_SUCCESS           Firmware volume handle created.
  57   @retval EFI_VOLUME_CORRUPTED  Volume was corrupt.
  58
  59 **/
  60 EFI_STATUS
  61 EFIAPI
  62 PeiFfsFvPpiProcessVolume (
  63   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,
  64   IN  VOID                               *Buffer,
  65   IN  UINTN                              BufferSize,
  66   OUT EFI_PEI_FV_HANDLE                  *FvHandle
  67   );
  68
  69 /**
  70   Finds the next file of the specified type.
  71
  72   This service enables PEI modules to discover additional firmware files.
  73   The FileHandle must be unique within the system.
  74
  75   @param This           Points to this instance of the
  76                         EFI_PEI_FIRMWARE_VOLUME_PPI.
  77   @param SearchType     A filter to find only files of this type. Type
  78                         EFI_FV_FILETYPE_ALL causes no filtering to be
  79                         done.
  80   @param FvHandle       Handle of firmware volume in which to
  81                         search.
  82   @param FileHandle     Points to the current handle from which to
  83                         begin searching or NULL to start at the
  84                         beginning of the firmware volume. Updated
  85                         upon return to reflect the file found.
  86
  87   @retval EFI_SUCCESS   The file was found.
  88   @retval EFI_NOT_FOUND The file was not found. FileHandle contains NULL.
  89
  90 **/
  91 EFI_STATUS
  92 EFIAPI
  93 PeiFfsFvPpiFindFileByType (
  94   IN CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,
  95   IN        EFI_FV_FILETYPE             SearchType,
  96   IN        EFI_PEI_FV_HANDLE           FvHandle,
  97   IN OUT    EFI_PEI_FILE_HANDLE         *FileHandle
  98   );
  99
 100 /**
 101   Find a file within a volume by its name.
 102
 103   This service searches for files with a specific name, within
 104   either the specified firmware volume or all firmware volumes.
 105
 106   @param This                   Points to this instance of the
 107                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
 108   @param FileName               A pointer to the name of the file to find
 109                                 within the firmware volume.
 110   @param FvHandle               Upon entry, the pointer to the firmware
 111                                 volume to search or NULL if all firmware
 112                                 volumes should be searched. Upon exit, the
 113                                 actual firmware volume in which the file was
 114                                 found.
 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   @retval EFI_NOT_FOUND         File was not found.
 120   @retval EFI_INVALID_PARAMETER FvHandle or FileHandle or
 121                                 FileName was NULL.
 122
 123
 124 **/
 125 EFI_STATUS
 126 EFIAPI
 127 PeiFfsFvPpiFindFileByName (
 128   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI *This,
 129   IN  CONST  EFI_GUID                    *FileName,
 130   IN  EFI_PEI_FV_HANDLE                  *FvHandle,
 131   OUT EFI_PEI_FILE_HANDLE                *FileHandle
 132   );
 133
 134 /**
 135   Find the next matching section in the firmware file.
 136
 137   This service enables PEI modules to discover sections
 138   of a given type within a valid file.
 139
 140   @param This             Points to this instance of the
 141                           EFI_PEI_FIRMWARE_VOLUME_PPI.
 142   @param SearchType       A filter to find only sections of this
 143                           type.
 144   @param FileHandle       Handle of firmware file in which to
 145                           search.
 146   @param SectionData      Updated upon  return to point to the
 147                           section found.
 148
 149   @retval EFI_SUCCESS     Section was found.
 150   @retval EFI_NOT_FOUND   Section of the specified type was not
 151                           found. SectionData contains NULL.
 152 **/
 153 EFI_STATUS
 154 EFIAPI
 155 PeiFfsFvPpiFindSectionByType (
 156   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI    *This,
 157   IN        EFI_SECTION_TYPE               SearchType,
 158   IN        EFI_PEI_FILE_HANDLE            FileHandle,
 159   OUT VOID                                 **SectionData
 160   );
 161
 162 /**
 163   Returns information about a specific file.
 164
 165   This function returns information about a specific
 166   file, including its file name, type, attributes, starting
 167   address and size.
 168
 169   @param This                     Points to this instance of the
 170                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 171   @param FileHandle               Handle of the file.
 172   @param FileInfo                 Upon exit, points to the file's
 173                                   information.
 174
 175   @retval EFI_SUCCESS             File information returned.
 176   @retval EFI_INVALID_PARAMETER   If FileHandle does not
 177                                   represent a valid file.
 178   @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.
 179
 180 **/
 181 EFI_STATUS
 182 EFIAPI
 183 PeiFfsFvPpiGetFileInfo (
 184   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 185   IN        EFI_PEI_FILE_HANDLE           FileHandle,
 186   OUT       EFI_FV_FILE_INFO              *FileInfo
 187   );
 188
 189 /**
 190   This function returns information about the firmware volume.
 191
 192   @param This                     Points to this instance of the
 193                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 194   @param FvHandle                 Handle to the firmware handle.
 195   @param VolumeInfo               Points to the returned firmware volume
 196                                   information.
 197
 198   @retval EFI_SUCCESS             Information returned successfully.
 199   @retval EFI_INVALID_PARAMETER   FvHandle does not indicate a valid
 200                                   firmware volume or VolumeInfo is NULL.
 201
 202 **/
 203 EFI_STATUS
 204 EFIAPI
 205 PeiFfsFvPpiGetVolumeInfo (
 206   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 207   IN  EFI_PEI_FV_HANDLE                    FvHandle,
 208   OUT EFI_FV_INFO                          *VolumeInfo
 209   );
 210
 211 /**
 212   Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE.
 213
 214   @param FvHandle   The handle of a FV.
 215
 216   @retval NULL if can not find.
 217   @return Pointer of corresponding PEI_CORE_FV_HANDLE.
 218 **/
 219 PEI_CORE_FV_HANDLE *
 220 FvHandleToCoreHandle (
 221   IN EFI_PEI_FV_HANDLE  FvHandle
 222   );
 223
 224 /**
 225   Given the input file pointer, search for the next matching file in the
 226   FFS volume as defined by SearchType. The search starts from FileHeader inside
 227   the Firmware Volume defined by FwVolHeader.
 228
 229
 230   @param FvHandle        Pointer to the FV header of the volume to search
 231   @param FileName        File name
 232   @param SearchType      Filter to find only files of this type.
 233                          Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
 234   @param FileHandle      This parameter must point to a valid FFS volume.
 235   @param AprioriFile     Pointer to AprioriFile image in this FV if has
 236
 237   @return EFI_NOT_FOUND  No files matching the search criteria were found
 238   @retval EFI_SUCCESS    Success to search given file
 239
 240 **/
 241 EFI_STATUS
 242 FindFileEx (
 243   IN  CONST EFI_PEI_FV_HANDLE        FvHandle,
 244   IN  CONST EFI_GUID                 *FileName,   OPTIONAL
 245   IN        EFI_FV_FILETYPE          SearchType,
 246   IN OUT    EFI_PEI_FILE_HANDLE      *FileHandle,
 247   IN OUT    EFI_PEI_FV_HANDLE        *AprioriFile  OPTIONAL
 248   );
 249
 250 /**
 251   Report the information for a new discoveried FV in unknown format.
 252
 253   If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been install for specifical FV format, but
 254   the FV in this FV format has been discoveried, then the information of this FV
 255   will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array.
 256   Also a notification would be installed for unknown FV format guid, if EFI_PEI_FIRMWARE_VOLUME_PPI
 257   is installed later by platform's PEIM, the original unknown FV will be processed by
 258   using new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
 259
 260   @param PrivateData  Point to instance of PEI_CORE_INSTANCE
 261   @param Format       Point to the unknown FV format guid.
 262   @param FvInfo       Point to FvInfo buffer.
 263   @param FvInfoSize   The size of FvInfo buffer.
 264
 265   @retval EFI_OUT_OF_RESOURCES  The FV info array in PEI_CORE_INSTANCE has no more spaces.
 266   @retval EFI_SUCCESS           Success to add the information for unknown FV.
 267 **/
 268 EFI_STATUS
 269 AddUnknownFormatFvInfo (
 270   IN PEI_CORE_INSTANCE *PrivateData,
 271   IN EFI_GUID          *Format,
 272   IN VOID              *FvInfo,
 273   IN UINT32            FvInfoSize
 274   );
 275
 276 /**
 277   Find the FV information according to FV format guid.
 278
 279   This routine also will remove the FV information found by given FV format guid from
 280   PrivateData->UnknownFvInfo[].
 281
 282   @param PrivateData      Point to instance of PEI_CORE_INSTANCE
 283   @param Format           Point to given FV format guid
 284   @param FvInfo           On return, the pointer of FV information buffer in given FV format guid
 285   @param FvInfoSize       On return, the size of FV information buffer.
 286
 287   @retval EFI_NOT_FOUND  The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI
 288   @retval EFI_SUCCESS    Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
 289 **/
 290 EFI_STATUS
 291 FindUnknownFormatFvInfo (
 292   IN  PEI_CORE_INSTANCE *PrivateData,
 293   IN  EFI_GUID          *Format,
 294   OUT VOID              **FvInfo,
 295   OUT UINT32            *FvInfoSize
 296   );
 297
 298 /**
 299   Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI.
 300
 301   When a EFI_PEI_FIRMWARE_VOLUME_PPI is installed to support new FV format, this
 302   routine is called to process all discoveried FVs in this format.
 303
 304   @param PeiServices       An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation
 305   @param NotifyDescriptor  Address of the notification descriptor data structure.
 306   @param Ppi               Address of the PPI that was installed.
 307
 308   @retval EFI_SUCCESS  The notification callback is processed correctly.
 309 **/
 310 EFI_STATUS
 311 EFIAPI
 312 ThirdPartyFvPpiNotifyCallback (
 313   IN EFI_PEI_SERVICES              **PeiServices,
 314   IN EFI_PEI_NOTIFY_DESCRIPTOR     *NotifyDescriptor,
 315   IN VOID                          *Ppi
 316   );
 317
 318 #endif