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 typedef UINT32  EFI_FV_FILE_ATTRIBUTES;
 119
 120 #define EFI_FV_FILE_ATTRIB_ALIGNMENT  0x0000001F
 121
 122 /**
 123   Read the requested file (NameGuid) and returns data in Buffer.
 124
 125   @param  This                  Calling context
 126   @param  NameGuid              Filename identifying which file to read
 127   @param  Buffer                Pointer to pointer to buffer in which contents of file are returned.
 128                                 <br>
 129                                 If Buffer is NULL, only type, attributes, and size are returned as
 130                                 there is no output buffer.
 131                                 <br>
 132                                 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 133                                 from BS pool by ReadFile
 134                                 <br>
 135                                 If Buffer != NULL and *Buffer != NULL, the output buffer has been
 136                                 allocated by the caller and is being passed in.
 137   @param  BufferSize            Indicates the buffer size passed in, and on output the size
 138                                 required to complete the read
 139   @param  FoundType             Indicates the type of the file who's data is returned
 140   @param  FileAttributes        Indicates the attributes of the file who's data is resturned
 141   @param  AuthenticationStatus  Indicates the authentication status of the data
 142
 143   @retval EFI_SUCCESS
 144   @retval EFI_WARN_BUFFER_TOO_SMALL
 145   @retval EFI_NOT_FOUND
 146   @retval EFI_DEVICE_ERROR
 147   @retval EFI_ACCESS_DENIED
 148
 149 **/
 150 typedef
 151 EFI_STATUS
 152 (EFIAPI *EFI_FV_READ_FILE) (
 153   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 154   IN EFI_GUID                       *NameGuid,
 155   IN OUT VOID                       **Buffer,
 156   IN OUT UINTN                      *BufferSize,
 157   OUT EFI_FV_FILETYPE               *FoundType,
 158   OUT EFI_FV_FILE_ATTRIBUTES        *FileAttributes,
 159   OUT UINT32                        *AuthenticationStatus
 160   );
 161
 162 /**
 163   Read the requested section from the specified file and returns data in Buffer.
 164
 165   @param  This                  Calling context
 166   @param  NameGuid              Filename identifying the file from which to read
 167   @param  SectionType           Indicates what section type to retrieve
 168   @param  SectionInstance       Indicates which instance of SectionType to retrieve
 169   @param  Buffer                Pointer to pointer to buffer in which contents of file are returned.
 170                                 <br>
 171                                 If Buffer is NULL, only type, attributes, and size are returned as
 172                                 there is no output buffer.
 173                                 <br>
 174                                 If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 175                                 from BS pool by ReadFile
 176                                 <br>
 177                                 If Buffer != NULL and *Buffer != NULL, the output buffer has been
 178                                 allocated by the caller and is being passed in.
 179   @param  BufferSize            Indicates the buffer size passed in, and on output the size
 180                                 required to complete the read
 181   @param  AuthenticationStatus  Indicates the authentication status of the data
 182
 183   @retval EFI_SUCCESS
 184   @retval EFI_WARN_BUFFER_TOO_SMALL
 185   @retval EFI_OUT_OF_RESOURCES
 186   @retval EFI_NOT_FOUND
 187   @retval EFI_DEVICE_ERROR
 188   @retval EFI_ACCESS_DENIED
 189
 190 **/
 191 typedef
 192 EFI_STATUS
 193 (EFIAPI *EFI_FV_READ_SECTION) (
 194   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 195   IN EFI_GUID                       *NameGuid,
 196   IN EFI_SECTION_TYPE               SectionType,
 197   IN UINTN                          SectionInstance,
 198   IN OUT VOID                       **Buffer,
 199   IN OUT UINTN                      *BufferSize,
 200   OUT UINT32                        *AuthenticationStatus
 201   );
 202
 203 typedef UINT32  EFI_FV_WRITE_POLICY;
 204
 205 #define EFI_FV_UNRELIABLE_WRITE 0x00000000
 206 #define EFI_FV_RELIABLE_WRITE   0x00000001
 207
 208 typedef struct {
 209   EFI_GUID                *NameGuid;
 210   EFI_FV_FILETYPE         Type;
 211   EFI_FV_FILE_ATTRIBUTES  FileAttributes;
 212   VOID                    *Buffer;
 213   UINT32                  BufferSize;
 214 } EFI_FV_WRITE_FILE_DATA;
 215
 216 /**
 217   Write the supplied file (NameGuid) to the FV.
 218
 219   @param  This                  Calling context
 220   @param  NumberOfFiles         Indicates the number of file records pointed to by FileData
 221   @param  WritePolicy           Indicates the level of reliability of the write with respect to
 222                                 things like power failure events.
 223   @param  FileData              A pointer to an array of EFI_FV_WRITE_FILE_DATA structures. Each
 224                                 element in the array indicates a file to write, and there are
 225                                 NumberOfFiles elements in the input array.
 226
 227   @retval EFI_SUCCESS
 228   @retval EFI_OUT_OF_RESOURCES
 229   @retval EFI_DEVICE_ERROR
 230   @retval EFI_WRITE_PROTECTED
 231   @retval EFI_NOT_FOUND
 232   @retval EFI_INVALID_PARAMETER
 233
 234 **/
 235 typedef
 236 EFI_STATUS
 237 (EFIAPI *EFI_FV_WRITE_FILE) (
 238   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 239   IN UINT32                         NumberOfFiles,
 240   IN EFI_FV_WRITE_POLICY            WritePolicy,
 241   IN EFI_FV_WRITE_FILE_DATA         *FileData
 242   );
 243
 244 /**
 245   Given the input key, search for the next matching file in the volume.
 246
 247   @param  This                  Calling context
 248   @param  Key                   Pointer to a caller allocated buffer that contains an implementation
 249                                 specific key that is used to track where to begin searching on
 250                                 successive calls.
 251   @param  FileType              Indicates the file type to filter for
 252   @param  NameGuid              Guid filename of the file found
 253   @param  Attributes            Attributes of the file found
 254   @param  Size                  Size in bytes of the file found
 255
 256   @retval EFI_SUCCESS
 257   @retval EFI_NOT_FOUND
 258   @retval EFI_DEVICE_ERROR
 259   @retval EFI_ACCESS_DENIED
 260
 261 **/
 262 typedef
 263 EFI_STATUS
 264 (EFIAPI *EFI_FV_GET_NEXT_FILE) (
 265   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 266   IN OUT VOID                       *Key,
 267   IN OUT EFI_FV_FILETYPE            *FileType,
 268   OUT EFI_GUID                      *NameGuid,
 269   OUT EFI_FV_FILE_ATTRIBUTES        *Attributes,
 270   OUT UINTN                         *Size
 271   );
 272
 273 /**
 274   @par Protocol Description:
 275   The Firmware Volume Protocol provides file-level access to the firmware volume.
 276   Each firmware volume driver must produce an instance of the Firmware Volume
 277   Protocol if the firmware volume is to be visible to the system. The Firmware
 278   Volume Protocol also provides mechanisms for determining and modifying some
 279   attributes of the firmware volume.
 280
 281   @param GetVolumeAttributes
 282   Retrieves volume capabilities and current settings.
 283
 284   @param SetVolumeAttributes
 285   Modifies the current settings of the firmware volume.
 286
 287   @param ReadFile
 288   Reads an entire file from the firmware volume.
 289
 290   @param ReadSection
 291   Reads a single section from a file into a buffer.
 292
 293   @param WriteFile
 294   Writes an entire file into the firmware volume.
 295
 296   @param GetNextFile
 297   Provides service to allow searching the firmware volume.
 298
 299   @param KeySize
 300   Data field that indicates the size in bytes of the Key input buffer for
 301   the GetNextFile() API.
 302
 303   @param ParentHandle
 304   Handle of the parent firmware volume.
 305
 306 **/
 307 struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
 308   EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;
 309   EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;
 310   EFI_FV_READ_FILE      ReadFile;
 311   EFI_FV_READ_SECTION   ReadSection;
 312   EFI_FV_WRITE_FILE     WriteFile;
 313   EFI_FV_GET_NEXT_FILE  GetNextFile;
 314   UINT32                KeySize;
 315   EFI_HANDLE            ParentHandle;
 316 };
 317
 318 extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
 319
 320 #endif