MdeModulePkg/Core/Pei/FwVol/FwVol.h

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