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