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