EdkCompatibilityPkg/Foundation/Framework/Protocol/FirmwareVolume/FirmwareVolume.h

   1 /*++
   2
   3 Copyright (c) 2004, Intel Corporation
   4 All rights reserved. This program and the accompanying materials
   5 are licensed and made available under the terms and conditions of the BSD License
   6 which accompanies this distribution.  The full text of the license may be found at
   7 http://opensource.org/licenses/bsd-license.php
   8
   9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  11
  12 Module Name:
  13
  14   FirmwareVolume.h
  15
  16 Abstract:
  17
  18   Firmware Volume protocol as defined in the Tiano Firmware Volume
  19   specification.
  20
  21 --*/
  22
  23 #ifndef _FW_VOL_H_
  24 #define _FW_VOL_H_
  25
  26 //
  27 // Statements that include other files
  28 //
  29 #include "EfiFirmwareVolumeHeader.h"
  30 #include "EfiFirmwareFileSystem.h"
  31 #include "EfiFirmwareVolume.h"
  32 //
  33 // Firmware Volume Protocol GUID definition
  34 //
  35 #define EFI_FIRMWARE_VOLUME_PROTOCOL_GUID \
  36   { \
  37     0x389F751F, 0x1838, 0x4388, {0x83, 0x90, 0xCD, 0x81, 0x54, 0xBD, 0x27, 0xF8} \
  38   }
  39
  40
  41 //
  42 // ************************************************************
  43 // EFI_FV_ATTRIBUTES bit definitions
  44 // ************************************************************
  45 //
  46 #define EFI_FV_READ_DISABLE_CAP       0x0000000000000001
  47 #define EFI_FV_READ_ENABLE_CAP        0x0000000000000002
  48 #define EFI_FV_READ_STATUS            0x0000000000000004
  49
  50 #define EFI_FV_WRITE_DISABLE_CAP      0x0000000000000008
  51 #define EFI_FV_WRITE_ENABLE_CAP       0x0000000000000010
  52 #define EFI_FV_WRITE_STATUS           0x0000000000000020
  53
  54 #define EFI_FV_LOCK_CAP               0x0000000000000040
  55 #define EFI_FV_LOCK_STATUS            0x0000000000000080
  56 #define EFI_FV_WRITE_POLICY_RELIABLE  0x0000000000000100
  57
  58 #define EFI_FV_ALIGNMENT_CAP          0x0000000000008000
  59 #define EFI_FV_ALIGNMENT_2            0x0000000000010000
  60 #define EFI_FV_ALIGNMENT_4            0x0000000000020000
  61 #define EFI_FV_ALIGNMENT_8            0x0000000000040000
  62 #define EFI_FV_ALIGNMENT_16           0x0000000000080000
  63 #define EFI_FV_ALIGNMENT_32           0x0000000000100000
  64 #define EFI_FV_ALIGNMENT_64           0x0000000000200000
  65 #define EFI_FV_ALIGNMENT_128          0x0000000000400000
  66 #define EFI_FV_ALIGNMENT_256          0x0000000000800000
  67 #define EFI_FV_ALIGNMENT_512          0x0000000001000000
  68 #define EFI_FV_ALIGNMENT_1K           0x0000000002000000
  69 #define EFI_FV_ALIGNMENT_2K           0x0000000004000000
  70 #define EFI_FV_ALIGNMENT_4K           0x0000000008000000
  71 #define EFI_FV_ALIGNMENT_8K           0x0000000010000000
  72 #define EFI_FV_ALIGNMENT_16K          0x0000000020000000
  73 #define EFI_FV_ALIGNMENT_32K          0x0000000040000000
  74 #define EFI_FV_ALIGNMENT_64K          0x0000000080000000
  75
  76 //
  77 // Protocol API definitions
  78 //
  79 //
  80 // Forward declaration of protocol data structure
  81 //
  82 typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL  EFI_FIRMWARE_VOLUME_PROTOCOL;
  83
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *FV_GET_ATTRIBUTES) (
  87   IN  EFI_FIRMWARE_VOLUME_PROTOCOL  * This,
  88   OUT EFI_FV_ATTRIBUTES             * Attributes
  89   );
  90
  91 /*++
  92
  93 Routine Description:
  94   Retrieves attributes, insures positive polarity of attribute bits, returns
  95   resulting attributes in output parameter
  96
  97 Arguments:
  98   This - Calling context
  99   Attributes - output buffer which contains attributes
 100
 101 Returns:
 102   EFI_INVALID_PARAMETER
 103   EFI_SUCCESS
 104
 105 --*/
 106 typedef
 107 EFI_STATUS
 108 (EFIAPI *FV_SET_ATTRIBUTES) (
 109   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 110   IN OUT EFI_FV_ATTRIBUTES          * Attributes
 111   );
 112
 113 /*++
 114
 115 Routine Description:
 116   Sets volume attributes
 117
 118 Arguments:
 119   This          Calling context
 120   Attributes    Buffer which contains attributes
 121
 122 Returns:
 123   EFI_INVALID_PARAMETER
 124   EFI_DEVICE_ERROR
 125   EFI_SUCCESS
 126
 127 --*/
 128
 129 typedef
 130 EFI_STATUS
 131 (EFIAPI *FV_READ_FILE) (
 132   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 133   IN EFI_GUID                       * NameGuid,
 134   IN OUT VOID                       **Buffer,
 135   IN OUT UINTN                      *BufferSize,
 136   OUT EFI_FV_FILETYPE               * FoundType,
 137   OUT EFI_FV_FILE_ATTRIBUTES        * FileAttributes,
 138   OUT UINT32                        *AuthenticationStatus
 139   );
 140
 141 /*++
 142
 143 Routine Description:
 144     Read the requested file (NameGuid) and returns data in Buffer.
 145
 146 Arguments:
 147   This - Calling context
 148   NameGuid - Filename identifying which file to read
 149   Buffer - Pointer to pointer to buffer in which contents of file are returned.
 150
 151           If Buffer is NULL, only type, attributes, and size are returned as
 152           there is no output buffer.
 153
 154           If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 155           from BS pool by ReadFile
 156
 157           If Buffer != NULL and *Buffer != NULL, the output buffer has been
 158           allocated by the caller and is being passed in.
 159
 160   BufferSize - Indicates the buffer size passed in, and on output the size
 161           required to complete the read
 162   FoundType - Indicates the type of the file who's data is returned
 163   FileAttributes - Indicates the attributes of the file who's data is resturned
 164   AuthenticationStatus - Indicates the authentication status of the data
 165
 166 Returns:
 167   EFI_SUCCESS
 168   EFI_WARN_BUFFER_TOO_SMALL
 169   EFI_NOT_FOUND
 170   EFI_DEVICE_ERROR
 171   EFI_ACCESS_DENIED
 172
 173 --*/
 174 typedef
 175 EFI_STATUS
 176 (EFIAPI *FV_READ_SECTION) (
 177   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 178   IN EFI_GUID                       * NameGuid,
 179   IN EFI_SECTION_TYPE               SectionType,
 180   IN UINTN                          SectionInstance,
 181   IN OUT VOID                       **Buffer,
 182   IN OUT UINTN                      *BufferSize,
 183   OUT UINT32                        *AuthenticationStatus
 184   );
 185
 186 /*++
 187
 188 Routine Description:
 189     Read the requested section from the specified file and returns data in Buffer.
 190
 191 Arguments:
 192   This - Calling context
 193   NameGuid - Filename identifying the file from which to read
 194   SectionType - Indicates what section type to retrieve
 195   SectionInstance - Indicates which instance of SectionType to retrieve
 196   Buffer - Pointer to pointer to buffer in which contents of file are returned.
 197
 198           If Buffer is NULL, only type, attributes, and size are returned as
 199           there is no output buffer.
 200
 201           If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 202           from BS pool by ReadFile
 203
 204           If Buffer != NULL and *Buffer != NULL, the output buffer has been
 205           allocated by the caller and is being passed in.
 206
 207   BufferSize - Indicates the buffer size passed in, and on output the size
 208           required to complete the read
 209   AuthenticationStatus - Indicates the authentication status of the data
 210
 211 Returns:
 212   EFI_SUCCESS
 213   EFI_WARN_BUFFER_TOO_SMALL
 214   EFI_OUT_OF_RESOURCES
 215   EFI_NOT_FOUND
 216   EFI_DEVICE_ERROR
 217   EFI_ACCESS_DENIED
 218
 219 --*/
 220
 221 typedef
 222 EFI_STATUS
 223 (EFIAPI *FV_WRITE_FILE) (
 224   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 225   IN UINT32                         NumberOfFiles,
 226   IN EFI_FV_WRITE_POLICY            WritePolicy,
 227   IN EFI_FV_WRITE_FILE_DATA         * FileData
 228   );
 229
 230 /*++
 231
 232 Routine Description:
 233   Write the supplied file (NameGuid) to the FV.
 234
 235 Arguments:
 236   This - Calling context
 237   NumberOfFiles - Indicates the number of file records pointed to by FileData
 238   WritePolicy - Indicates the level of reliability of the write with respect to
 239           things like power failure events.
 240   FileData - A pointer to an array of EFI_FV_WRITE_FILE_DATA structures.  Each
 241           element in the array indicates a file to write, and there are
 242           NumberOfFiles elements in the input array.
 243
 244 Returns:
 245   EFI_SUCCESS
 246   EFI_OUT_OF_RESOURCES
 247   EFI_DEVICE_ERROR
 248   EFI_WRITE_PROTECTED
 249   EFI_NOT_FOUND
 250   EFI_INVALID_PARAMETER
 251
 252 --*/
 253 typedef
 254 EFI_STATUS
 255 (EFIAPI *FV_GET_NEXT_FILE) (
 256   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 257   IN OUT VOID                       *Key,
 258   IN OUT EFI_FV_FILETYPE            * FileType,
 259   OUT EFI_GUID                      * NameGuid,
 260   OUT EFI_FV_FILE_ATTRIBUTES        * Attributes,
 261   OUT UINTN                         *Size
 262   );
 263
 264 /*++
 265
 266 Routine Description:
 267   Given the input key, search for the next matching file in the volume.
 268
 269 Arguments:
 270   This - Calling context
 271   Key - Pointer to a caller allocated buffer that contains an implementation
 272         specific key that is used to track where to begin searching on
 273         successive calls.
 274   FileType - Indicates the file type to filter for
 275   NameGuid - Guid filename of the file found
 276   Attributes - Attributes of the file found
 277   Size - Size in bytes of the file found
 278
 279 Returns:
 280   EFI_SUCCESS
 281   EFI_NOT_FOUND
 282   EFI_DEVICE_ERROR
 283   EFI_ACCESS_DENIED
 284
 285 --*/
 286 struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
 287   FV_GET_ATTRIBUTES GetVolumeAttributes;
 288   FV_SET_ATTRIBUTES SetVolumeAttributes;
 289   FV_READ_FILE      ReadFile;
 290   FV_READ_SECTION   ReadSection;
 291   FV_WRITE_FILE     WriteFile;
 292   FV_GET_NEXT_FILE  GetNextFile;
 293   UINT32            KeySize;
 294   EFI_HANDLE        ParentHandle;
 295 };
 296
 297 extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
 298
 299 #endif