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