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