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