IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h

   1 /** @file
   2   This file declares Firmware Volume protocol.
   3   The Firmware Volume Protocol provides file-level access to the firmware volume.E ach firmware
   4   volume driver must produce an instance of the Firmware Volume Protocol if the firmware volume
   5   is to be visible to the system.T he Firmware Volume Protocol also provides mechanisms for
   6   determining and modifying some attributes of the firmware volume.
   7
   8   Copyright (c) 2007, Intel Corporation
   9   All rights reserved. This program and the accompanying materials
  10   are licensed and made available under the terms and conditions of the BSD License
  11   which accompanies this distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17   @par Revision Reference:
  18   This protocol is defined in Firmware Volume specification.
  19   Version 0.9
  20
  21 **/
  22
  23 #ifndef _FIRMWARE_VOLUME_H_
  24 #define _FIRMWARE_VOLUME_H_
  25
  26 #include <PiDxe.h>
  27
  28 //
  29 // Firmware Volume Protocol GUID definition
  30 //
  31 #define EFI_FIRMWARE_VOLUME_PROTOCOL_GUID \
  32   { \
  33     0x389F751F, 0x1838, 0x4388, {0x83, 0x90, 0xCD, 0x81, 0x54, 0xBD, 0x27, 0xF8 } \
  34   }
  35
  36 #define FV_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '_')
  37
  38 typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL  EFI_FIRMWARE_VOLUME_PROTOCOL;
  39
  40 //
  41 // FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions
  42 //
  43 typedef UINT64  FRAMEWORK_EFI_FV_ATTRIBUTES;
  44
  45 //
  46 // ************************************************************
  47 // FRAMEWORK_EFI_FV_ATTRIBUTES bit definitions
  48 // ************************************************************
  49 //
  50 #define EFI_FV_READ_DISABLE_CAP       0x0000000000000001ULL
  51 #define EFI_FV_READ_ENABLE_CAP        0x0000000000000002ULL
  52 #define EFI_FV_READ_STATUS            0x0000000000000004ULL
  53
  54 #define EFI_FV_WRITE_DISABLE_CAP      0x0000000000000008ULL
  55 #define EFI_FV_WRITE_ENABLE_CAP       0x0000000000000010ULL
  56 #define EFI_FV_WRITE_STATUS           0x0000000000000020ULL
  57
  58 #define EFI_FV_LOCK_CAP               0x0000000000000040ULL
  59 #define EFI_FV_LOCK_STATUS            0x0000000000000080ULL
  60 #define EFI_FV_WRITE_POLICY_RELIABLE  0x0000000000000100ULL
  61
  62 #define EFI_FV_ALIGNMENT_CAP          0x0000000000008000ULL
  63 #define EFI_FV_ALIGNMENT_2            0x0000000000010000ULL
  64 #define EFI_FV_ALIGNMENT_4            0x0000000000020000ULL
  65 #define EFI_FV_ALIGNMENT_8            0x0000000000040000ULL
  66 #define EFI_FV_ALIGNMENT_16           0x0000000000080000ULL
  67 #define EFI_FV_ALIGNMENT_32           0x0000000000100000ULL
  68 #define EFI_FV_ALIGNMENT_64           0x0000000000200000ULL
  69 #define EFI_FV_ALIGNMENT_128          0x0000000000400000ULL
  70 #define EFI_FV_ALIGNMENT_256          0x0000000000800000ULL
  71 #define EFI_FV_ALIGNMENT_512          0x0000000001000000ULL
  72 #define EFI_FV_ALIGNMENT_1K           0x0000000002000000ULL
  73 #define EFI_FV_ALIGNMENT_2K           0x0000000004000000ULL
  74 #define EFI_FV_ALIGNMENT_4K           0x0000000008000000ULL
  75 #define EFI_FV_ALIGNMENT_8K           0x0000000010000000ULL
  76 #define EFI_FV_ALIGNMENT_16K          0x0000000020000000ULL
  77 #define EFI_FV_ALIGNMENT_32K          0x0000000040000000ULL
  78 #define EFI_FV_ALIGNMENT_64K          0x0000000080000000ULL
  79
  80 //
  81 // Protocol API definitions
  82 //
  83
  84 /**
  85   Retrieves attributes, insures positive polarity of attribute bits, returns
  86   resulting attributes in output parameter
  87
  88   @param  This                  Calling context
  89   @param  Attributes            output buffer which contains attributes
  90
  91   @retval EFI_INVALID_PARAMETER
  92   @retval EFI_SUCCESS
  93
  94 **/
  95 typedef
  96 EFI_STATUS
  97 (EFIAPI *FRAMEWORK_EFI_FV_GET_ATTRIBUTES)(
  98   IN  EFI_FIRMWARE_VOLUME_PROTOCOL            *This,
  99   OUT FRAMEWORK_EFI_FV_ATTRIBUTES             *Attributes
 100   );
 101
 102 /**
 103   Sets volume attributes
 104
 105   @param  This                  Calling context
 106   @param  Attributes            Buffer which contains attributes
 107
 108   @retval EFI_INVALID_PARAMETER
 109   @retval EFI_DEVICE_ERROR
 110   @retval EFI_SUCCESS
 111
 112 **/
 113 typedef
 114 EFI_STATUS
 115 (EFIAPI *FRAMEWORK_EFI_FV_SET_ATTRIBUTES)(
 116   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 117   IN OUT FRAMEWORK_EFI_FV_ATTRIBUTES          *Attributes
 118   );
 119
 120 /**
 121   Read the requested file (NameGuid) and returns data in Buffer.
 122
 123   @param  This                  Calling context
 124   @param  NameGuid              Filename identifying which file to read
 125   @param  Buffer                Pointer to pointer to buffer in which contents of file are returned.
 126                                 <br>
 127                                 If Buffer is NULL, only type, attributes, and size are returned as
 128                                 there is no output buffer.
 129                                 <br>
 130                                 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 131                                 from BS pool by ReadFile
 132                                 <br>
 133                                 If Buffer != NULL and *Buffer != NULL, the output buffer has been
 134                                 allocated by the caller and is being passed in.
 135   @param  BufferSize            Indicates the buffer size passed in, and on output the size
 136                                 required to complete the read
 137   @param  FoundType             Indicates the type of the file who's data is returned
 138   @param  FileAttributes        Indicates the attributes of the file who's data is resturned
 139   @param  AuthenticationStatus  Indicates the authentication status of the data
 140
 141   @retval EFI_SUCCESS
 142   @retval EFI_WARN_BUFFER_TOO_SMALL
 143   @retval EFI_NOT_FOUND
 144   @retval EFI_DEVICE_ERROR
 145   @retval EFI_ACCESS_DENIED
 146
 147 **/
 148 typedef
 149 EFI_STATUS
 150 (EFIAPI *FRAMEWORK_EFI_FV_READ_FILE)(
 151   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 152   IN EFI_GUID                       *NameGuid,
 153   IN OUT VOID                       **Buffer,
 154   IN OUT UINTN                      *BufferSize,
 155   OUT EFI_FV_FILETYPE               *FoundType,
 156   OUT EFI_FV_FILE_ATTRIBUTES        *FileAttributes,
 157   OUT UINT32                        *AuthenticationStatus
 158   );
 159
 160 /**
 161   Read the requested section from the specified file and returns data in Buffer.
 162
 163   @param  This                  Calling context
 164   @param  NameGuid              Filename identifying the file from which to read
 165   @param  SectionType           Indicates what section type to retrieve
 166   @param  SectionInstance       Indicates which instance of SectionType to retrieve
 167   @param  Buffer                Pointer to pointer to buffer in which contents of file are returned.
 168                                 <br>
 169                                 If Buffer is NULL, only type, attributes, and size are returned as
 170                                 there is no output buffer.
 171                                 <br>
 172                                 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 173                                 from BS pool by ReadFile
 174                                 <br>
 175                                 If Buffer != NULL and *Buffer != NULL, the output buffer has been
 176                                 allocated by the caller and is being passed in.
 177   @param  BufferSize            Indicates the buffer size passed in, and on output the size
 178                                 required to complete the read
 179   @param  AuthenticationStatus  Indicates the authentication status of the data
 180
 181   @retval EFI_SUCCESS
 182   @retval EFI_WARN_BUFFER_TOO_SMALL
 183   @retval EFI_OUT_OF_RESOURCES
 184   @retval EFI_NOT_FOUND
 185   @retval EFI_DEVICE_ERROR
 186   @retval EFI_ACCESS_DENIED
 187
 188 **/
 189 typedef
 190 EFI_STATUS
 191 (EFIAPI *FRAMEWORK_EFI_FV_READ_SECTION)(
 192   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 193   IN EFI_GUID                       *NameGuid,
 194   IN EFI_SECTION_TYPE               SectionType,
 195   IN UINTN                          SectionInstance,
 196   IN OUT VOID                       **Buffer,
 197   IN OUT UINTN                      *BufferSize,
 198   OUT UINT32                        *AuthenticationStatus
 199   );
 200
 201 typedef UINT32  FRAMEWORK_EFI_FV_WRITE_POLICY;
 202
 203 #define FRAMEWORK_EFI_FV_UNRELIABLE_WRITE 0x00000000
 204 #define FRAMEWORK_EFI_FV_RELIABLE_WRITE   0x00000001
 205
 206 typedef struct {
 207   EFI_GUID                *NameGuid;
 208   EFI_FV_FILETYPE         Type;
 209   EFI_FV_FILE_ATTRIBUTES  FileAttributes;
 210   VOID                    *Buffer;
 211   UINT32                  BufferSize;
 212 } FRAMEWORK_EFI_FV_WRITE_FILE_DATA;
 213
 214 /**
 215   Write the supplied file (NameGuid) to the FV.
 216
 217   @param  This                  Calling context
 218   @param  NumberOfFiles         Indicates the number of file records pointed to by FileData
 219   @param  WritePolicy           Indicates the level of reliability of the write with respect to
 220                                 things like power failure events.
 221   @param  FileData              A pointer to an array of EFI_FV_WRITE_FILE_DATA structures. Each
 222                                 element in the array indicates a file to write, and there are
 223                                 NumberOfFiles elements in the input array.
 224
 225   @retval EFI_SUCCESS
 226   @retval EFI_OUT_OF_RESOURCES
 227   @retval EFI_DEVICE_ERROR
 228   @retval EFI_WRITE_PROTECTED
 229   @retval EFI_NOT_FOUND
 230   @retval EFI_INVALID_PARAMETER
 231
 232 **/
 233 typedef
 234 EFI_STATUS
 235 (EFIAPI *FRAMEWORK_EFI_FV_WRITE_FILE)(
 236   IN EFI_FIRMWARE_VOLUME_PROTOCOL             *This,
 237   IN UINT32                                   NumberOfFiles,
 238   IN FRAMEWORK_EFI_FV_WRITE_POLICY            WritePolicy,
 239   IN FRAMEWORK_EFI_FV_WRITE_FILE_DATA         *FileData
 240   );
 241
 242 /**
 243   Given the input key, search for the next matching file in the volume.
 244
 245   @param  This                  Calling context
 246   @param  Key                   Pointer to a caller allocated buffer that contains an implementation
 247                                 specific key that is used to track where to begin searching on
 248                                 successive calls.
 249   @param  FileType              Indicates the file type to filter for
 250   @param  NameGuid              Guid filename of the file found
 251   @param  Attributes            Attributes of the file found
 252   @param  Size                  Size in bytes of the file found
 253
 254   @retval EFI_SUCCESS
 255   @retval EFI_NOT_FOUND
 256   @retval EFI_DEVICE_ERROR
 257   @retval EFI_ACCESS_DENIED
 258
 259 **/
 260 typedef
 261 EFI_STATUS
 262 (EFIAPI *FRAMEWORK_EFI_FV_GET_NEXT_FILE)(
 263   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 264   IN OUT VOID                       *Key,
 265   IN OUT EFI_FV_FILETYPE            *FileType,
 266   OUT EFI_GUID                      *NameGuid,
 267   OUT EFI_FV_FILE_ATTRIBUTES        *Attributes,
 268   OUT UINTN                         *Size
 269   );
 270
 271 /**
 272   @par Protocol Description:
 273   The Firmware Volume Protocol provides file-level access to the firmware volume.
 274   Each firmware volume driver must produce an instance of the Firmware Volume
 275   Protocol if the firmware volume is to be visible to the system. The Firmware
 276   Volume Protocol also provides mechanisms for determining and modifying some
 277   attributes of the firmware volume.
 278
 279   @param GetVolumeAttributes
 280   Retrieves volume capabilities and current settings.
 281
 282   @param SetVolumeAttributes
 283   Modifies the current settings of the firmware volume.
 284
 285   @param ReadFile
 286   Reads an entire file from the firmware volume.
 287
 288   @param ReadSection
 289   Reads a single section from a file into a buffer.
 290
 291   @param WriteFile
 292   Writes an entire file into the firmware volume.
 293
 294   @param GetNextFile
 295   Provides service to allow searching the firmware volume.
 296
 297   @param KeySize
 298   Data field that indicates the size in bytes of the Key input buffer for
 299   the GetNextFile() API.
 300
 301   @param ParentHandle
 302   Handle of the parent firmware volume.
 303
 304 **/
 305 struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
 306   FRAMEWORK_EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;
 307   FRAMEWORK_EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;
 308   FRAMEWORK_EFI_FV_READ_FILE      ReadFile;
 309   FRAMEWORK_EFI_FV_READ_SECTION   ReadSection;
 310   FRAMEWORK_EFI_FV_WRITE_FILE     WriteFile;
 311   FRAMEWORK_EFI_FV_GET_NEXT_FILE  GetNextFile;
 312   UINT32                KeySize;
 313   EFI_HANDLE            ParentHandle;
 314 };
 315
 316 extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
 317
 318 #endif