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 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   Find the next matching section in the firmware file.
 164
 165   This service enables PEI modules to discover sections
 166   of a given instance and type within a valid file.
 167
 168   @param This                   Points to this instance of the
 169                                 EFI_PEI_FIRMWARE_VOLUME_PPI.
 170   @param SearchType             A filter to find only sections of this
 171                                 type.
 172   @param SearchInstance         A filter to find the specific instance
 173                                 of sections.
 174   @param FileHandle             Handle of firmware file in which to
 175                                 search.
 176   @param SectionData            Updated upon return to point to the
 177                                 section found.
 178   @param AuthenticationStatus   Updated upon return to point to the
 179                                 authentication status for this section.
 180
 181   @retval EFI_SUCCESS     Section was found.
 182   @retval EFI_NOT_FOUND   Section of the specified type was not
 183                           found. SectionData contains NULL.
 184 **/
 185 EFI_STATUS
 186 EFIAPI
 187 PeiFfsFvPpiFindSectionByType2 (
 188   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI    *This,
 189   IN        EFI_SECTION_TYPE               SearchType,
 190   IN        UINTN                          SearchInstance,
 191   IN        EFI_PEI_FILE_HANDLE            FileHandle,
 192   OUT VOID                                 **SectionData,
 193   OUT UINT32                               *AuthenticationStatus
 194   );
 195
 196 /**
 197   Returns information about a specific file.
 198
 199   This function returns information about a specific
 200   file, including its file name, type, attributes, starting
 201   address and size.
 202
 203   @param This                     Points to this instance of the
 204                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 205   @param FileHandle               Handle of the file.
 206   @param FileInfo                 Upon exit, points to the file's
 207                                   information.
 208
 209   @retval EFI_SUCCESS             File information returned.
 210   @retval EFI_INVALID_PARAMETER   If FileHandle does not
 211                                   represent a valid file.
 212   @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.
 213
 214 **/
 215 EFI_STATUS
 216 EFIAPI
 217 PeiFfsFvPpiGetFileInfo (
 218   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 219   IN        EFI_PEI_FILE_HANDLE           FileHandle,
 220   OUT       EFI_FV_FILE_INFO              *FileInfo
 221   );
 222
 223 /**
 224   Returns information about a specific file.
 225
 226   This function returns information about a specific
 227   file, including its file name, type, attributes, starting
 228   address, size and authentication status.
 229
 230   @param This                     Points to this instance of the
 231                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 232   @param FileHandle               Handle of the file.
 233   @param FileInfo                 Upon exit, points to the file's
 234                                   information.
 235
 236   @retval EFI_SUCCESS             File information returned.
 237   @retval EFI_INVALID_PARAMETER   If FileHandle does not
 238                                   represent a valid file.
 239   @retval EFI_INVALID_PARAMETER   If FileInfo is NULL.
 240
 241 **/
 242 EFI_STATUS
 243 EFIAPI
 244 PeiFfsFvPpiGetFileInfo2 (
 245   IN  CONST EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 246   IN        EFI_PEI_FILE_HANDLE           FileHandle,
 247   OUT       EFI_FV_FILE_INFO2             *FileInfo
 248   );
 249
 250 /**
 251   This function returns information about the firmware volume.
 252
 253   @param This                     Points to this instance of the
 254                                   EFI_PEI_FIRMWARE_VOLUME_PPI.
 255   @param FvHandle                 Handle to the firmware handle.
 256   @param VolumeInfo               Points to the returned firmware volume
 257                                   information.
 258
 259   @retval EFI_SUCCESS             Information returned successfully.
 260   @retval EFI_INVALID_PARAMETER   FvHandle does not indicate a valid
 261                                   firmware volume or VolumeInfo is NULL.
 262
 263 **/
 264 EFI_STATUS
 265 EFIAPI
 266 PeiFfsFvPpiGetVolumeInfo (
 267   IN  CONST  EFI_PEI_FIRMWARE_VOLUME_PPI   *This,
 268   IN  EFI_PEI_FV_HANDLE                    FvHandle,
 269   OUT EFI_FV_INFO                          *VolumeInfo
 270   );
 271
 272 /**
 273   Convert the handle of FV to pointer of corresponding PEI_CORE_FV_HANDLE.
 274
 275   @param FvHandle   The handle of a FV.
 276
 277   @retval NULL if can not find.
 278   @return Pointer of corresponding PEI_CORE_FV_HANDLE.
 279 **/
 280 PEI_CORE_FV_HANDLE *
 281 FvHandleToCoreHandle (
 282   IN EFI_PEI_FV_HANDLE  FvHandle
 283   );
 284
 285 /**
 286   Given the input file pointer, search for the next matching file in the
 287   FFS volume as defined by SearchType. The search starts from FileHeader inside
 288   the Firmware Volume defined by FwVolHeader.
 289
 290
 291   @param FvHandle        Pointer to the FV header of the volume to search
 292   @param FileName        File name
 293   @param SearchType      Filter to find only files of this type.
 294                          Type EFI_FV_FILETYPE_ALL causes no filtering to be done.
 295   @param FileHandle      This parameter must point to a valid FFS volume.
 296   @param AprioriFile     Pointer to AprioriFile image in this FV if has
 297
 298   @return EFI_NOT_FOUND  No files matching the search criteria were found
 299   @retval EFI_SUCCESS    Success to search given file
 300
 301 **/
 302 EFI_STATUS
 303 FindFileEx (
 304   IN  CONST EFI_PEI_FV_HANDLE        FvHandle,
 305   IN  CONST EFI_GUID                 *FileName,   OPTIONAL
 306   IN        EFI_FV_FILETYPE          SearchType,
 307   IN OUT    EFI_PEI_FILE_HANDLE      *FileHandle,
 308   IN OUT    EFI_PEI_FV_HANDLE        *AprioriFile  OPTIONAL
 309   );
 310
 311 /**
 312   Report the information for a new discoveried FV in unknown format.
 313
 314   If the EFI_PEI_FIRMWARE_VOLUME_PPI has not been installed for specifical FV format, but
 315   the FV in this FV format has been discoveried, then the information of this FV
 316   will be cached into PEI_CORE_INSTANCE's UnknownFvInfo array.
 317   Also a notification would be installed for unknown FV format guid, if EFI_PEI_FIRMWARE_VOLUME_PPI
 318   is installed later by platform's PEIM, the original unknown FV will be processed by
 319   using new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
 320
 321   @param PrivateData  Point to instance of PEI_CORE_INSTANCE
 322   @param FvInfo2Ppi   Point to FvInfo2 PPI.
 323
 324   @retval EFI_OUT_OF_RESOURCES  The FV info array in PEI_CORE_INSTANCE has no more spaces.
 325   @retval EFI_SUCCESS           Success to add the information for unknown FV.
 326 **/
 327 EFI_STATUS
 328 AddUnknownFormatFvInfo (
 329   IN PEI_CORE_INSTANCE                  *PrivateData,
 330   IN EFI_PEI_FIRMWARE_VOLUME_INFO2_PPI  *FvInfo2Ppi
 331   );
 332
 333 /**
 334   Find the FV information according to FV format guid.
 335
 336   This routine also will remove the FV information found by given FV format guid from
 337   PrivateData->UnknownFvInfo[].
 338
 339   @param PrivateData      Point to instance of PEI_CORE_INSTANCE
 340   @param Format           Point to given FV format guid
 341   @param FvInfo           On return, the pointer of FV information buffer in given FV format guid
 342   @param FvInfoSize       On return, the size of FV information buffer.
 343   @param AuthenticationStatus On return, the authentication status of FV information buffer.
 344
 345   @retval EFI_NOT_FOUND  The FV is not found for new installed EFI_PEI_FIRMWARE_VOLUME_PPI
 346   @retval EFI_SUCCESS    Success to find a FV which could be processed by new installed EFI_PEI_FIRMWARE_VOLUME_PPI.
 347 **/
 348 EFI_STATUS
 349 FindUnknownFormatFvInfo (
 350   IN  PEI_CORE_INSTANCE *PrivateData,
 351   IN  EFI_GUID          *Format,
 352   OUT VOID              **FvInfo,
 353   OUT UINT32            *FvInfoSize,
 354   OUT UINT32            *AuthenticationStatus
 355   );
 356
 357 /**
 358   Notification callback function for EFI_PEI_FIRMWARE_VOLUME_PPI.
 359
 360   When a EFI_PEI_FIRMWARE_VOLUME_PPI is installed to support new FV format, this
 361   routine is called to process all discoveried FVs in this format.
 362
 363   @param PeiServices       An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation
 364   @param NotifyDescriptor  Address of the notification descriptor data structure.
 365   @param Ppi               Address of the PPI that was installed.
 366
 367   @retval EFI_SUCCESS  The notification callback is processed correctly.
 368 **/
 369 EFI_STATUS
 370 EFIAPI
 371 ThirdPartyFvPpiNotifyCallback (
 372   IN EFI_PEI_SERVICES              **PeiServices,
 373   IN EFI_PEI_NOTIFY_DESCRIPTOR     *NotifyDescriptor,
 374   IN VOID                          *Ppi
 375   );
 376
 377 #endif