MdeModulePkg/Core/Dxe/FwVolDriver.h

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