MdeModulePkg/Core/Dxe/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, Intel Corporation
   6 All rights reserved. This program and the accompanying materials
   7 are licensed and made available under the terms and conditions of the BSD License
   8 which accompanies this distribution.  The full text of the license may be found at
   9 http://opensource.org/licenses/bsd-license.php
  10
  11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  13
  14 **/
  15
  16 #ifndef __FWVOL_H
  17 #define __FWVOL_H
  18
  19
  20 #define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')
  21
  22 //
  23 // Used to track all non-deleted files
  24 //
  25 typedef struct {
  26   LIST_ENTRY                      Link;
  27   EFI_FFS_FILE_HEADER             *FfsHeader;
  28   UINTN                           StreamHandle;
  29 } FFS_FILE_LIST_ENTRY;
  30
  31 typedef struct {
  32   UINTN                                   Signature;
  33   EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *Fvb;
  34   EFI_HANDLE                              Handle;
  35   EFI_FIRMWARE_VOLUME2_PROTOCOL           Fv;
  36
  37   EFI_FIRMWARE_VOLUME_HEADER              *FwVolHeader;
  38   UINT8                                   *CachedFv;
  39   UINT8                                   *EndOfCachedFv;
  40
  41   FFS_FILE_LIST_ENTRY                     *LastKey;
  42
  43   LIST_ENTRY                              FfsFileListHeader;
  44
  45   UINT8                                   ErasePolarity;
  46 } FV_DEVICE;
  47
  48 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
  49
  50
  51 EFI_STATUS
  52 EFIAPI
  53 FvGetVolumeAttributes (
  54   IN    CONST EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
  55   OUT         EFI_FV_ATTRIBUTES              *Attributes
  56   )
  57 /*++
  58
  59 Routine Description:
  60     Retrieves attributes, insures positive polarity of attribute bits, returns
  61     resulting attributes in output parameter
  62
  63 Arguments:
  64     This        - Calling context
  65     Attributes  - output buffer which contains attributes
  66
  67 Returns:
  68     EFI_SUCCESS         - Successfully got volume attributes
  69
  70 --*/
  71 ;
  72
  73 EFI_STATUS
  74 EFIAPI
  75 FvSetVolumeAttributes (
  76   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
  77   IN OUT    EFI_FV_ATTRIBUTES              *Attributes
  78   )
  79 /*++
  80
  81 Routine Description:
  82     Sets current attributes for volume
  83
  84 Arguments:
  85     This       - Calling context
  86     Attributes - At input, contains attributes to be set.  At output contains
  87       new value of FV
  88
  89 Returns:
  90     EFI_UNSUPPORTED   - Could not be set.
  91 --*/
  92 ;
  93
  94 EFI_STATUS
  95 EFIAPI
  96 FvGetNextFile (
  97   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL  *This,
  98   IN OUT    VOID                           *Key,
  99   IN OUT    EFI_FV_FILETYPE                *FileType,
 100   OUT       EFI_GUID                       *NameGuid,
 101   OUT       EFI_FV_FILE_ATTRIBUTES         *Attributes,
 102   OUT       UINTN                          *Size
 103   )
 104 /*++
 105
 106 Routine Description:
 107     Given the input key, search for the next matching file in the volume.
 108
 109 Arguments:
 110     This          -   Indicates the calling context.
 111     FileType      -   FileType is a pointer to a caller allocated
 112                       EFI_FV_FILETYPE. The GetNextFile() API can filter it's
 113                       search for files based on the value of *FileType input.
 114                       A *FileType input of 0 causes GetNextFile() to search for
 115                       files of all types.  If a file is found, the file's type
 116                       is returned in *FileType.  *FileType is not modified if
 117                       no file is found.
 118     Key           -   Key is a pointer to a caller allocated buffer that
 119                       contains implementation specific data that is used to
 120                       track where to begin the search for the next file.
 121                       The size of the buffer must be at least This->KeySize
 122                       bytes long. To reinitialize the search and begin from
 123                       the beginning of the firmware volume, the entire buffer
 124                       must be cleared to zero. Other than clearing the buffer
 125                       to initiate a new search, the caller must not modify the
 126                       data in the buffer between calls to GetNextFile().
 127     NameGuid      -   NameGuid is a pointer to a caller allocated EFI_GUID.
 128                       If a file is found, the file's name is returned in
 129                       *NameGuid.  *NameGuid is not modified if no file is
 130                       found.
 131     Attributes    -   Attributes is a pointer to a caller allocated
 132                       EFI_FV_FILE_ATTRIBUTES.  If a file is found, the file's
 133                       attributes are returned in *Attributes. *Attributes is
 134                       not modified if no file is found.
 135     Size          -   Size is a pointer to a caller allocated UINTN.
 136                       If a file is found, the file's size is returned in *Size.
 137                       *Size is not modified if no file is found.
 138
 139 Returns:
 140     EFI_SUCCESS                 - Successfully find the file.
 141     EFI_DEVICE_ERROR            - Device error.
 142     EFI_ACCESS_DENIED           - Fv could not read.
 143     EFI_NOT_FOUND               - No matching file found.
 144     EFI_INVALID_PARAMETER       - Invalid parameter
 145
 146 --*/
 147 ;
 148
 149
 150 EFI_STATUS
 151 EFIAPI
 152 FvReadFile (
 153   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
 154   IN CONST  EFI_GUID                       *NameGuid,
 155   IN OUT    VOID                           **Buffer,
 156   IN OUT    UINTN                          *BufferSize,
 157   OUT       EFI_FV_FILETYPE                *FoundType,
 158   OUT       EFI_FV_FILE_ATTRIBUTES         *FileAttributes,
 159   OUT       UINT32                         *AuthenticationStatus
 160   )
 161 /*++
 162
 163 Routine Description:
 164     Locates a file in the firmware volume and
 165     copies it to the supplied buffer.
 166
 167 Arguments:
 168     This              -   Indicates the calling context.
 169     NameGuid          -   Pointer to an EFI_GUID, which is the filename.
 170     Buffer            -   Buffer is a pointer to pointer to a buffer in
 171                           which the file or section contents or are returned.
 172     BufferSize        -   BufferSize is a pointer to caller allocated
 173                           UINTN. On input *BufferSize indicates the size
 174                           in bytes of the memory region pointed to by
 175                           Buffer. On output, *BufferSize contains the number
 176                           of bytes required to read the file.
 177     FoundType         -   FoundType is a pointer to a caller allocated
 178                           EFI_FV_FILETYPE that on successful return from Read()
 179                           contains the type of file read.  This output reflects
 180                           the file type irrespective of the value of the
 181                           SectionType input.
 182     FileAttributes    -   FileAttributes is a pointer to a caller allocated
 183                           EFI_FV_FILE_ATTRIBUTES.  On successful return from
 184                           Read(), *FileAttributes contains the attributes of
 185                           the file read.
 186     AuthenticationStatus -  AuthenticationStatus is a pointer to a caller
 187                           allocated UINTN in which the authentication status
 188                           is returned.
 189 Returns:
 190     EFI_SUCCESS                   - Successfully read to memory buffer.
 191     EFI_WARN_BUFFER_TOO_SMALL     - Buffer too small.
 192     EFI_NOT_FOUND                 - Not found.
 193     EFI_DEVICE_ERROR              - Device error.
 194     EFI_ACCESS_DENIED             - Could not read.
 195     EFI_INVALID_PARAMETER         - Invalid parameter.
 196     EFI_OUT_OF_RESOURCES          - Not enough buffer to be allocated.
 197
 198 --*/
 199 ;
 200
 201 EFI_STATUS
 202 EFIAPI
 203 FvReadFileSection (
 204   IN CONST  EFI_FIRMWARE_VOLUME2_PROTOCOL   *This,
 205   IN CONST  EFI_GUID                       *NameGuid,
 206   IN        EFI_SECTION_TYPE               SectionType,
 207   IN        UINTN                          SectionInstance,
 208   IN OUT    VOID                           **Buffer,
 209   IN OUT    UINTN                          *BufferSize,
 210   OUT       UINT32                         *AuthenticationStatus
 211   )
 212 /*++
 213
 214   Routine Description:
 215     Locates a section in a given FFS File and
 216     copies it to the supplied buffer (not including section header).
 217
 218   Arguments:
 219     This              -   Indicates the calling context.
 220     NameGuid          -   Pointer to an EFI_GUID, which is the filename.
 221     SectionType       -   Indicates the section type to return.
 222     SectionInstance   -   Indicates which instance of sections with a type of
 223                           SectionType to return.
 224     Buffer            -   Buffer is a pointer to pointer to a buffer in which
 225                           the file or section contents or are returned.
 226     BufferSize        -   BufferSize is a pointer to caller allocated UINTN.
 227     AuthenticationStatus -AuthenticationStatus is a pointer to a caller
 228                           allocated UINT32 in which the authentication status
 229                           is returned.
 230
 231   Returns:
 232     EFI_SUCCESS                     - Successfully read the file section into buffer.
 233     EFI_WARN_BUFFER_TOO_SMALL       - Buffer too small.
 234     EFI_NOT_FOUND                   - Section not found.
 235     EFI_DEVICE_ERROR                - Device error.
 236     EFI_ACCESS_DENIED               - Could not read.
 237     EFI_INVALID_PARAMETER           - Invalid parameter.
 238
 239 --*/
 240 ;
 241
 242 EFI_STATUS
 243 EFIAPI
 244 FvWriteFile (
 245   IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL       *This,
 246   IN       UINT32                             NumberOfFiles,
 247   IN       EFI_FV_WRITE_POLICY                WritePolicy,
 248   IN       EFI_FV_WRITE_FILE_DATA             *FileData
 249   )
 250 /*++
 251
 252     Routine Description:
 253       Writes one or more files to the firmware volume.
 254
 255     Arguments:
 256     This        - Indicates the calling context.
 257     WritePolicy - WritePolicy indicates the level of reliability for
 258                   the write in the event of a power failure or other
 259                   system failure during the write operation.
 260     FileData    - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
 261                   Each element of FileData[] represents a file to be written.
 262
 263     Returns:
 264       EFI_SUCCESS                   - Files successfully written to firmware volume
 265       EFI_OUT_OF_RESOURCES          - Not enough buffer to be allocated.
 266       EFI_DEVICE_ERROR              - Device error.
 267       EFI_WRITE_PROTECTED           - Write protected.
 268       EFI_NOT_FOUND                 - Not found.
 269       EFI_INVALID_PARAMETER         - Invalid parameter.
 270       EFI_UNSUPPORTED               - This function not supported.
 271
 272 --*/
 273 ;
 274
 275 EFI_STATUS
 276 EFIAPI
 277 FvGetVolumeInfo (
 278   IN  CONST EFI_FIRMWARE_VOLUME2_PROTOCOL       *This,
 279   IN  CONST EFI_GUID                            *InformationType,
 280   IN  OUT   UINTN                               *BufferSize,
 281   OUT       VOID                                *Buffer
 282   )
 283 /*++
 284
 285 Routine Description:
 286   Return information of type InformationType for the requested firmware
 287   volume.
 288
 289 Arguments:
 290     This                - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 291     InformationType     - InformationType for requested.
 292     BufferSize          - On input, size of Buffer.On output, the amount of
 293                           data returned in Buffer.
 294     Buffer              - A poniter to the data buffer to return.
 295 Returns:
 296     EFI_SUCCESS         - Successfully got volume Information.
 297
 298 --*/
 299 ;
 300
 301
 302 EFI_STATUS
 303 EFIAPI
 304 FvSetVolumeInfo (
 305   IN  CONST EFI_FIRMWARE_VOLUME2_PROTOCOL       *This,
 306   IN  CONST EFI_GUID                            *InformationType,
 307   IN        UINTN                               BufferSize,
 308   IN  CONST  VOID                               *Buffer
 309   )
 310 /*++
 311
 312 Routine Description:
 313   Set information of type InformationType for the requested firmware
 314   volume.
 315
 316 Arguments:
 317     This                - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
 318     InformationType     - InformationType for requested.
 319     BufferSize          - On input, size of Buffer.On output, the amount of
 320                           data returned in Buffer.
 321     Buffer              - A poniter to the data buffer to return.
 322 Returns:
 323     EFI_SUCCESS         - Successfully set volume Information.
 324
 325 --*/
 326 ;
 327
 328 //
 329 //Internal functions
 330 //
 331 typedef enum {
 332   EfiCheckSumUint8    = 0,
 333   EfiCheckSumUint16   = 1,
 334   EfiCheckSumUint32   = 2,
 335   EfiCheckSumUint64   = 3,
 336   EfiCheckSumMaximum  = 4
 337 } EFI_CHECKSUM_TYPE;
 338
 339
 340 BOOLEAN
 341 IsBufferErased (
 342   IN UINT8    ErasePolarity,
 343   IN VOID     *Buffer,
 344   IN UINTN    BufferSize
 345   )
 346 /*++
 347
 348 Routine Description:
 349   Check if a block of buffer is erased
 350
 351 Arguments:
 352   ErasePolarity -  Erase polarity attribute of the firmware volume
 353   Buffer        -  The buffer to be checked
 354   BufferSize    -  Size of the buffer in bytes
 355
 356 Returns:
 357   TRUE  -  The block of buffer is erased
 358   FALSE -  The block of buffer is not erased
 359
 360 --*/
 361 ;
 362
 363 EFI_FFS_FILE_STATE
 364 GetFileState (
 365   IN UINT8                ErasePolarity,
 366   IN EFI_FFS_FILE_HEADER  *FfsHeader
 367   )
 368 /*++
 369
 370 Routine Description:
 371   Get the FFS file state by checking the highest bit set in the header's state field
 372
 373 Arguments:
 374   ErasePolarity -  Erase polarity attribute of the firmware volume
 375   FfsHeader     -  Points to the FFS file header
 376
 377 Returns:
 378   FFS File state
 379
 380 --*/
 381 ;
 382
 383 VOID
 384 SetFileState (
 385   IN UINT8                State,
 386   IN EFI_FFS_FILE_HEADER  *FfsHeader
 387   )
 388 /*++
 389
 390 Routine Description:
 391   Set the FFS file state.
 392
 393 Arguments:
 394   State         -  The state to be set.
 395   FfsHeader     -  Points to the FFS file header
 396
 397 Returns:
 398   None.
 399
 400 --*/
 401 ;
 402
 403 BOOLEAN
 404 VerifyFvHeaderChecksum (
 405   IN EFI_FIRMWARE_VOLUME_HEADER *FvHeader
 406   )
 407 /*++
 408
 409 Routine Description:
 410   Verify checksum of the firmware volume header
 411
 412 Arguments:
 413   FvHeader  -  Points to the firmware volume header to be checked
 414
 415 Returns:
 416   TRUE  -  Checksum verification passed
 417   FALSE -  Checksum verification failed
 418
 419 --*/
 420 ;
 421
 422 BOOLEAN
 423 IsValidFfsHeader (
 424   IN  UINT8                ErasePolarity,
 425   IN  EFI_FFS_FILE_HEADER  *FfsHeader,
 426   OUT EFI_FFS_FILE_STATE   *FileState
 427   )
 428 /*++
 429
 430 Routine Description:
 431   Check if it's a valid FFS file header
 432
 433 Arguments:
 434   ErasePolarity -  Erase polarity attribute of the firmware volume
 435   FfsHeader     -  Points to the FFS file header to be checked
 436   FileState     -  FFS file state to be returned
 437
 438 Returns:
 439   TRUE  -  Valid FFS file header
 440   FALSE -  Invalid FFS file header
 441
 442 --*/
 443 ;
 444
 445 BOOLEAN
 446 IsValidFfsFile (
 447   IN UINT8                ErasePolarity,
 448   IN EFI_FFS_FILE_HEADER  *FfsHeader
 449   )
 450 /*++
 451
 452 Routine Description:
 453   Check if it's a valid FFS file.
 454   Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
 455
 456 Arguments:
 457   ErasePolarity -  Erase polarity attribute of the firmware volume
 458   FfsHeader     -  Points to the FFS file to be checked
 459
 460 Returns:
 461   TRUE  -  Valid FFS file
 462   FALSE -  Invalid FFS file
 463
 464 --*/
 465 ;
 466
 467 EFI_STATUS
 468 GetFwVolHeader (
 469   IN  EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL      *Fvb,
 470   OUT EFI_FIRMWARE_VOLUME_HEADER              **FwVolHeader
 471   )
 472 /*++
 473
 474 Routine Description:
 475   given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
 476   copy the volume header into it.
 477
 478 Arguments:
 479   Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
 480           header
 481   FwVolHeader - Pointer to pointer to allocated buffer in which the volume
 482                   header is returned.
 483
 484 Returns:
 485   Status code.
 486
 487 --*/
 488 ;
 489
 490
 491 EFI_STATUS
 492 FvCheck (
 493   IN OUT FV_DEVICE  *FvDevice
 494   )
 495 /*++
 496
 497 Routine Description:
 498   Check if a FV is consistent and allocate cache
 499
 500 Arguments:
 501   FvDevice - pointer to the FvDevice to be checked.
 502
 503 Returns:
 504   EFI_OUT_OF_RESOURCES    - Not enough buffer to be allocated.
 505   EFI_SUCCESS             - FV is consistent and cache is allocated.
 506   EFI_VOLUME_CORRUPTED    - File system is corrupted.
 507
 508 --*/
 509 ;
 510
 511 #endif