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