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