MdeModulePkg/Core/Pei/FwVol/FwVol.h

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