MdePkg/Include/Protocol/FirmwareVolume.h

   1 /** @file
   2   This file declares Firmware Volume protocol.
   3
   4   Copyright (c) 2006, 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
 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
 180   @param  BufferSize Indicates the buffer size passed in, and on output the size
 181   required to complete the read
 182   @param  AuthenticationStatus Indicates the authentication status of the data
 183
 184   @retval EFI_SUCCESS
 185   @retval EFI_WARN_BUFFER_TOO_SMALL
 186   @retval EFI_OUT_OF_RESOURCES
 187   @retval EFI_NOT_FOUND
 188   @retval EFI_DEVICE_ERROR
 189   @retval EFI_ACCESS_DENIED
 190
 191 **/
 192 typedef
 193 EFI_STATUS
 194 (EFIAPI *EFI_FV_READ_SECTION) (
 195   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 196   IN EFI_GUID                       *NameGuid,
 197   IN EFI_SECTION_TYPE               SectionType,
 198   IN UINTN                          SectionInstance,
 199   IN OUT VOID                       **Buffer,
 200   IN OUT UINTN                      *BufferSize,
 201   OUT UINT32                        *AuthenticationStatus
 202   );
 203
 204 typedef UINT32  EFI_FV_WRITE_POLICY;
 205
 206 #define EFI_FV_UNRELIABLE_WRITE 0x00000000
 207 #define EFI_FV_RELIABLE_WRITE   0x00000001
 208
 209 typedef struct {
 210   EFI_GUID                *NameGuid;
 211   EFI_FV_FILETYPE         Type;
 212   EFI_FV_FILE_ATTRIBUTES  FileAttributes;
 213   VOID                    *Buffer;
 214   UINT32                  BufferSize;
 215 } EFI_FV_WRITE_FILE_DATA;
 216
 217 /**
 218   Write the supplied file (NameGuid) to the FV.
 219
 220   @param  This Calling context
 221   @param  NumberOfFiles Indicates the number of file records pointed to by FileData
 222   @param  WritePolicy Indicates the level of reliability of the write with respect to
 223   things like power failure events.
 224   @param  FileData A pointer to an array of EFI_FV_WRITE_FILE_DATA structures.  Each
 225   element in the array indicates a file to write, and there are
 226   NumberOfFiles elements in the input array.
 227
 228   @retval EFI_SUCCESS
 229   @retval EFI_OUT_OF_RESOURCES
 230   @retval EFI_DEVICE_ERROR
 231   @retval EFI_WRITE_PROTECTED
 232   @retval EFI_NOT_FOUND
 233   @retval EFI_INVALID_PARAMETER
 234
 235 **/
 236 typedef
 237 EFI_STATUS
 238 (EFIAPI *EFI_FV_WRITE_FILE) (
 239   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 240   IN UINT32                         NumberOfFiles,
 241   IN EFI_FV_WRITE_POLICY            WritePolicy,
 242   IN EFI_FV_WRITE_FILE_DATA         *FileData
 243   );
 244
 245 /**
 246   Given the input key, search for the next matching file in the volume.
 247
 248   @param  This Calling context
 249   @param  Key Pointer to a caller allocated buffer that contains an implementation
 250   specific key that is used to track where to begin searching on
 251   successive calls.
 252   @param  FileType Indicates the file type to filter for
 253   @param  NameGuid Guid filename of the file found
 254   @param  Attributes Attributes of the file found
 255   @param  Size Size in bytes of the file found
 256
 257   @retval EFI_SUCCESS
 258   @retval EFI_NOT_FOUND
 259   @retval EFI_DEVICE_ERROR
 260   @retval EFI_ACCESS_DENIED
 261
 262 **/
 263 typedef
 264 EFI_STATUS
 265 (EFIAPI *EFI_FV_GET_NEXT_FILE) (
 266   IN EFI_FIRMWARE_VOLUME_PROTOCOL   *This,
 267   IN OUT VOID                       *Key,
 268   IN OUT EFI_FV_FILETYPE            *FileType,
 269   OUT EFI_GUID                      *NameGuid,
 270   OUT EFI_FV_FILE_ATTRIBUTES        *Attributes,
 271   OUT UINTN                         *Size
 272   );
 273
 274 /**
 275   @par Protocol Description:
 276   The Firmware Volume Protocol provides file-level access to the firmware volume.
 277   Each firmware volume driver must produce an instance of the Firmware Volume
 278   Protocol if the firmware volume is to be visible to the system. The Firmware
 279   Volume Protocol also provides mechanisms for determining and modifying some
 280   attributes of the firmware volume.
 281
 282   @param GetVolumeAttributes
 283   Retrieves volume capabilities and current settings.
 284
 285   @param SetVolumeAttributes
 286   Modifies the current settings of the firmware volume.
 287
 288   @param ReadFile
 289   Reads an entire file from the firmware volume.
 290
 291   @param ReadSection
 292   Reads a single section from a file into a buffer.
 293
 294   @param WriteFile
 295   Writes an entire file into the firmware volume.
 296
 297   @param GetNextFile
 298   Provides service to allow searching the firmware volume.
 299
 300   @param KeySize
 301   Data field that indicates the size in bytes of the Key input buffer for
 302   the GetNextFile() API.
 303
 304   @param ParentHandle
 305   Handle of the parent firmware volume.
 306
 307 **/
 308 struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
 309   EFI_FV_GET_ATTRIBUTES GetVolumeAttributes;
 310   EFI_FV_SET_ATTRIBUTES SetVolumeAttributes;
 311   EFI_FV_READ_FILE      ReadFile;
 312   EFI_FV_READ_SECTION   ReadSection;
 313   EFI_FV_WRITE_FILE     WriteFile;
 314   EFI_FV_GET_NEXT_FILE  GetNextFile;
 315   UINT32                KeySize;
 316   EFI_HANDLE            ParentHandle;
 317 };
 318
 319 extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
 320
 321 #endif