MdeModulePkg/Core/Dxe/FwVolDriver.h

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