IntelFrameworkPkg/Include/Protocol/FirmwareVolume.h

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