MdeModulePkg/Core/Dxe/FwVol/FwVolDriver.h

   1 /** @file
   2   Firmware File System protocol. Layers on top of Firmware
   3   Block protocol to produce a file abstraction of FV based files.
   4
   5 Copyright (c) 2006 - 2014, Intel Corporation. All rights reserved.<BR>
   6 SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8 **/
   9
  10 #ifndef __FW_VOL_DRIVER_H_
  11 #define __FW_VOL_DRIVER_H_
  12
  13
  14 #define FV2_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '2')
  15
  16 //
  17 // Used to track all non-deleted files
  18 //
  19 typedef struct {
  20   LIST_ENTRY                      Link;
  21   EFI_FFS_FILE_HEADER             *FfsHeader;
  22   UINTN                           StreamHandle;
  23   BOOLEAN                         FileCached;
  24 } FFS_FILE_LIST_ENTRY;
  25
  26 typedef struct {
  27   UINTN                                   Signature;
  28   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *Fvb;
  29   EFI_HANDLE                              Handle;
  30   EFI_FIRMWARE_VOLUME2_PROTOCOL           Fv;
  31
  32   EFI_FIRMWARE_VOLUME_HEADER              *FwVolHeader;
  33   UINT8                                   *CachedFv;
  34   UINT8                                   *EndOfCachedFv;
  35
  36   FFS_FILE_LIST_ENTRY                     *LastKey;
  37
  38   LIST_ENTRY                              FfsFileListHeader;
  39
  40   UINT32                                  AuthenticationStatus;
  41   UINT8                                   ErasePolarity;
  42   BOOLEAN                                 IsFfs3Fv;
  43   BOOLEAN                                 IsMemoryMapped;
  44 } FV_DEVICE;
  45
  46 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
  47
  48 /**
  49   Retrieves attributes, insures positive polarity of attribute bits, returns
  50   resulting attributes in output parameter.
  51
  52   @param  This             Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
  53   @param  Attributes       output buffer which contains attributes.
  54
  55   @retval EFI_SUCCESS      Successfully got volume attributes.
  56
  57 **/
  58 EFI_STATUS
  59 EFIAPI
  60 FvGetVolumeAttributes (
  61   IN  CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
  62   OUT       EFI_FV_ATTRIBUTES             *Attributes
  63   );
  64
  65
  66 /**
  67   Sets current attributes for volume
  68
  69   @param  This             Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
  70   @param  Attributes       At input, contains attributes to be set.  At output
  71                            contains new value of FV.
  72
  73   @retval EFI_UNSUPPORTED  Could not be set.
  74
  75 **/
  76 EFI_STATUS
  77 EFIAPI
  78 FvSetVolumeAttributes (
  79   IN     CONST EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
  80   IN OUT       EFI_FV_ATTRIBUTES              *Attributes
  81   );
  82
  83
  84 /**
  85   Given the input key, search for the next matching file in the volume.
  86
  87   @param  This                       Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
  88   @param  Key                        Key is a pointer to a caller allocated
  89                                      buffer that contains implementation specific
  90                                      data that is used to track where to begin
  91                                      the search for the next file. The size of
  92                                      the buffer must be at least This->KeySize
  93                                      bytes long. To reinitialize the search and
  94                                      begin from the beginning of the firmware
  95                                      volume, the entire buffer must be cleared to
  96                                      zero. Other than clearing the buffer to
  97                                      initiate a new search, the caller must not
  98                                      modify the data in the buffer between calls
  99                                      to GetNextFile().
 100   @param  FileType                   FileType is a pointer to a caller allocated
 101                                      EFI_FV_FILETYPE. The GetNextFile() API can
 102                                      filter it's search for files based on the
 103                                      value of *FileType input. A *FileType input
 104                                      of 0 causes GetNextFile() to search for
 105                                      files of all types.  If a file is found, the
 106                                      file's type is returned in *FileType.
 107                                      *FileType is not modified if no file is
 108                                      found.
 109   @param  NameGuid                   NameGuid is a pointer to a caller allocated
 110                                      EFI_GUID. If a file is found, the file's
 111                                      name is returned in *NameGuid.  *NameGuid is
 112                                      not modified if no file is found.
 113   @param  Attributes                 Attributes is a pointer to a caller
 114                                      allocated EFI_FV_FILE_ATTRIBUTES.  If a file
 115                                      is found, the file's attributes are returned
 116                                      in *Attributes. *Attributes is not modified
 117                                      if no file is found.
 118   @param  Size                       Size is a pointer to a caller allocated
 119                                      UINTN. If a file is found, the file's size
 120                                      is returned in *Size. *Size is not modified
 121                                      if no file is found.
 122
 123   @retval EFI_SUCCESS                Successfully find the file.
 124   @retval EFI_DEVICE_ERROR           Device error.
 125   @retval EFI_ACCESS_DENIED          Fv could not read.
 126   @retval EFI_NOT_FOUND              No matching file found.
 127   @retval EFI_INVALID_PARAMETER      Invalid parameter
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 FvGetNextFile (
 133   IN CONST   EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 134   IN OUT     VOID                          *Key,
 135   IN OUT     EFI_FV_FILETYPE               *FileType,
 136   OUT        EFI_GUID                      *NameGuid,
 137   OUT        EFI_FV_FILE_ATTRIBUTES        *Attributes,
 138   OUT        UINTN                         *Size
 139   );
 140
 141
 142
 143 /**
 144   Locates a file in the firmware volume and
 145   copies it to the supplied buffer.
 146
 147   @param  This                       Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 148   @param  NameGuid                   Pointer to an EFI_GUID, which is the
 149                                      filename.
 150   @param  Buffer                     Buffer is a pointer to pointer to a buffer
 151                                      in which the file or section contents or are
 152                                      returned.
 153   @param  BufferSize                 BufferSize is a pointer to caller allocated
 154                                      UINTN. On input *BufferSize indicates the
 155                                      size in bytes of the memory region pointed
 156                                      to by Buffer. On output, *BufferSize
 157                                      contains the number of bytes required to
 158                                      read the file.
 159   @param  FoundType                  FoundType is a pointer to a caller allocated
 160                                      EFI_FV_FILETYPE that on successful return
 161                                      from Read() contains the type of file read.
 162                                      This output reflects the file type
 163                                      irrespective of the value of the SectionType
 164                                      input.
 165   @param  FileAttributes             FileAttributes is a pointer to a caller
 166                                      allocated EFI_FV_FILE_ATTRIBUTES.  On
 167                                      successful return from Read(),
 168                                      *FileAttributes contains the attributes of
 169                                      the file read.
 170   @param  AuthenticationStatus       AuthenticationStatus is a pointer to a
 171                                      caller allocated UINTN in which the
 172                                      authentication status is returned.
 173
 174   @retval EFI_SUCCESS                Successfully read to memory buffer.
 175   @retval EFI_WARN_BUFFER_TOO_SMALL  Buffer too small.
 176   @retval EFI_NOT_FOUND              Not found.
 177   @retval EFI_DEVICE_ERROR           Device error.
 178   @retval EFI_ACCESS_DENIED          Could not read.
 179   @retval EFI_INVALID_PARAMETER      Invalid parameter.
 180   @retval EFI_OUT_OF_RESOURCES       Not enough buffer to be allocated.
 181
 182 **/
 183 EFI_STATUS
 184 EFIAPI
 185 FvReadFile (
 186   IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL *This,
 187   IN CONST EFI_GUID                      *NameGuid,
 188   IN OUT   VOID                          **Buffer,
 189   IN OUT   UINTN                         *BufferSize,
 190   OUT      EFI_FV_FILETYPE               *FoundType,
 191   OUT      EFI_FV_FILE_ATTRIBUTES        *FileAttributes,
 192   OUT      UINT32                        *AuthenticationStatus
 193   );
 194
 195
 196 /**
 197   Locates a section in a given FFS File and
 198   copies it to the supplied buffer (not including section header).
 199
 200   @param  This                       Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 201   @param  NameGuid                   Pointer to an EFI_GUID, which is the
 202                                      filename.
 203   @param  SectionType                Indicates the section type to return.
 204   @param  SectionInstance            Indicates which instance of sections with a
 205                                      type of SectionType to return.
 206   @param  Buffer                     Buffer is a pointer to pointer to a buffer
 207                                      in which the file or section contents or are
 208                                      returned.
 209   @param  BufferSize                 BufferSize is a pointer to caller allocated
 210                                      UINTN.
 211   @param  AuthenticationStatus       AuthenticationStatus is a pointer to a
 212                                      caller allocated UINT32 in which the
 213                                      authentication status is returned.
 214
 215   @retval EFI_SUCCESS                Successfully read the file section into
 216                                      buffer.
 217   @retval EFI_WARN_BUFFER_TOO_SMALL  Buffer too small.
 218   @retval EFI_NOT_FOUND              Section not found.
 219   @retval EFI_DEVICE_ERROR           Device error.
 220   @retval EFI_ACCESS_DENIED          Could not read.
 221   @retval EFI_INVALID_PARAMETER      Invalid parameter.
 222
 223 **/
 224 EFI_STATUS
 225 EFIAPI
 226 FvReadFileSection (
 227   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
 228   IN CONST  EFI_GUID                       *NameGuid,
 229   IN        EFI_SECTION_TYPE               SectionType,
 230   IN        UINTN                          SectionInstance,
 231   IN OUT    VOID                           **Buffer,
 232   IN OUT    UINTN                          *BufferSize,
 233   OUT       UINT32                         *AuthenticationStatus
 234   );
 235
 236
 237 /**
 238   Writes one or more files to the firmware volume.
 239
 240   @param  This                   Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 241   @param  NumberOfFiles          Number of files.
 242   @param  WritePolicy            WritePolicy indicates the level of reliability
 243                                  for the write in the event of a power failure or
 244                                  other system failure during the write operation.
 245   @param  FileData               FileData is an pointer to an array of
 246                                  EFI_FV_WRITE_DATA. Each element of array
 247                                  FileData represents a file to be written.
 248
 249   @retval EFI_SUCCESS            Files successfully written to firmware volume
 250   @retval EFI_OUT_OF_RESOURCES   Not enough buffer to be allocated.
 251   @retval EFI_DEVICE_ERROR       Device error.
 252   @retval EFI_WRITE_PROTECTED    Write protected.
 253   @retval EFI_NOT_FOUND          Not found.
 254   @retval EFI_INVALID_PARAMETER  Invalid parameter.
 255   @retval EFI_UNSUPPORTED        This function not supported.
 256
 257 **/
 258 EFI_STATUS
 259 EFIAPI
 260 FvWriteFile (
 261   IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
 262   IN       UINT32                         NumberOfFiles,
 263   IN       EFI_FV_WRITE_POLICY            WritePolicy,
 264   IN       EFI_FV_WRITE_FILE_DATA         *FileData
 265   );
 266
 267
 268 /**
 269   Return information of type InformationType for the requested firmware
 270   volume.
 271
 272   @param  This             Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 273   @param  InformationType  InformationType for requested.
 274   @param  BufferSize       On input, size of Buffer.On output, the amount of data
 275                            returned in Buffer.
 276   @param  Buffer           A poniter to the data buffer to return.
 277
 278   @retval EFI_SUCCESS      Successfully got volume Information.
 279
 280 **/
 281 EFI_STATUS
 282 EFIAPI
 283 FvGetVolumeInfo (
 284   IN  CONST EFI_FIRMWARE_VOLUME2_PROTOCOL       *This,
 285   IN  CONST EFI_GUID                            *InformationType,
 286   IN OUT UINTN                                  *BufferSize,
 287   OUT VOID                                      *Buffer
 288   );
 289
 290
 291
 292 /**
 293   Set information of type InformationType for the requested firmware
 294   volume.
 295
 296   @param  This             Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 297   @param  InformationType  InformationType for requested.
 298   @param  BufferSize       On input, size of Buffer.On output, the amount of data
 299                            returned in Buffer.
 300   @param  Buffer           A poniter to the data buffer to return.
 301
 302   @retval EFI_SUCCESS      Successfully set volume Information.
 303
 304 **/
 305 EFI_STATUS
 306 EFIAPI
 307 FvSetVolumeInfo (
 308   IN  CONST EFI_FIRMWARE_VOLUME2_PROTOCOL       *This,
 309   IN  CONST EFI_GUID                            *InformationType,
 310   IN  UINTN                                     BufferSize,
 311   IN CONST  VOID                                *Buffer
 312   );
 313
 314
 315
 316 /**
 317   Check if a block of buffer is erased.
 318
 319   @param  ErasePolarity  Erase polarity attribute of the firmware volume
 320   @param  InBuffer       The buffer to be checked
 321   @param  BufferSize     Size of the buffer in bytes
 322
 323   @retval TRUE           The block of buffer is erased
 324   @retval FALSE          The block of buffer is not erased
 325
 326 **/
 327 BOOLEAN
 328 IsBufferErased (
 329   IN UINT8    ErasePolarity,
 330   IN VOID     *InBuffer,
 331   IN UINTN    BufferSize
 332   );
 333
 334
 335 /**
 336   Get the FFS file state by checking the highest bit set in the header's state field.
 337
 338   @param  ErasePolarity  Erase polarity attribute of the firmware volume
 339   @param  FfsHeader      Points to the FFS file header
 340
 341   @return FFS File state
 342
 343 **/
 344 EFI_FFS_FILE_STATE
 345 GetFileState (
 346   IN UINT8                ErasePolarity,
 347   IN EFI_FFS_FILE_HEADER  *FfsHeader
 348   );
 349
 350
 351 /**
 352   Set the FFS file state.
 353
 354   @param  State                      The state to be set.
 355   @param  FfsHeader                  Points to the FFS file header
 356
 357   @return None.
 358
 359 **/
 360 VOID
 361 SetFileState (
 362   IN UINT8                State,
 363   IN EFI_FFS_FILE_HEADER  *FfsHeader
 364   );
 365
 366 /**
 367   Check if it's a valid FFS file header.
 368
 369   @param  ErasePolarity  Erase polarity attribute of the firmware volume
 370   @param  FfsHeader      Points to the FFS file header to be checked
 371   @param  FileState      FFS file state to be returned
 372
 373   @retval TRUE           Valid FFS file header
 374   @retval FALSE          Invalid FFS file header
 375
 376 **/
 377 BOOLEAN
 378 IsValidFfsHeader (
 379   IN UINT8                ErasePolarity,
 380   IN EFI_FFS_FILE_HEADER  *FfsHeader,
 381   OUT EFI_FFS_FILE_STATE  *FileState
 382   );
 383
 384
 385 /**
 386   Check if it's a valid FFS file.
 387   Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
 388
 389   @param  ErasePolarity  Erase polarity attribute of the firmware volume
 390   @param  FfsHeader      Points to the FFS file to be checked
 391
 392   @retval TRUE           Valid FFS file
 393   @retval FALSE          Invalid FFS file
 394
 395 **/
 396 BOOLEAN
 397 IsValidFfsFile (
 398   IN UINT8                ErasePolarity,
 399   IN EFI_FFS_FILE_HEADER  *FfsHeader
 400   );
 401
 402 #endif