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