MdeModulePkg/Core/Pei/FwVol/FwVol.h

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