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 EFI_FORWARD_DECLARATION (EFI_FIRMWARE_VOLUME_PROTOCOL);
  42
  43 //
  44 // ************************************************************
  45 // EFI_FV_ATTRIBUTES bit definitions
  46 // ************************************************************
  47 //
  48 #define EFI_FV_READ_DISABLE_CAP       0x0000000000000001
  49 #define EFI_FV_READ_ENABLE_CAP        0x0000000000000002
  50 #define EFI_FV_READ_STATUS            0x0000000000000004
  51
  52 #define EFI_FV_WRITE_DISABLE_CAP      0x0000000000000008
  53 #define EFI_FV_WRITE_ENABLE_CAP       0x0000000000000010
  54 #define EFI_FV_WRITE_STATUS           0x0000000000000020
  55
  56 #define EFI_FV_LOCK_CAP               0x0000000000000040
  57 #define EFI_FV_LOCK_STATUS            0x0000000000000080
  58 #define EFI_FV_WRITE_POLICY_RELIABLE  0x0000000000000100
  59
  60 #define EFI_FV_ALIGNMENT_CAP          0x0000000000008000
  61 #define EFI_FV_ALIGNMENT_2            0x0000000000010000
  62 #define EFI_FV_ALIGNMENT_4            0x0000000000020000
  63 #define EFI_FV_ALIGNMENT_8            0x0000000000040000
  64 #define EFI_FV_ALIGNMENT_16           0x0000000000080000
  65 #define EFI_FV_ALIGNMENT_32           0x0000000000100000
  66 #define EFI_FV_ALIGNMENT_64           0x0000000000200000
  67 #define EFI_FV_ALIGNMENT_128          0x0000000000400000
  68 #define EFI_FV_ALIGNMENT_256          0x0000000000800000
  69 #define EFI_FV_ALIGNMENT_512          0x0000000001000000
  70 #define EFI_FV_ALIGNMENT_1K           0x0000000002000000
  71 #define EFI_FV_ALIGNMENT_2K           0x0000000004000000
  72 #define EFI_FV_ALIGNMENT_4K           0x0000000008000000
  73 #define EFI_FV_ALIGNMENT_8K           0x0000000010000000
  74 #define EFI_FV_ALIGNMENT_16K          0x0000000020000000
  75 #define EFI_FV_ALIGNMENT_32K          0x0000000040000000
  76 #define EFI_FV_ALIGNMENT_64K          0x0000000080000000
  77
  78 //
  79 // Protocol API definitions
  80 //
  81 //
  82 // Forward declaration of protocol data structure
  83 //
  84 typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL  EFI_FIRMWARE_VOLUME_PROTOCOL;
  85
  86 typedef
  87 EFI_STATUS
  88 (EFIAPI *FV_GET_ATTRIBUTES) (
  89   IN  EFI_FIRMWARE_VOLUME_PROTOCOL  * This,
  90   OUT EFI_FV_ATTRIBUTES             * Attributes
  91   );
  92
  93 /*++
  94
  95 Routine Description:
  96   Retrieves attributes, insures positive polarity of attribute bits, returns
  97   resulting attributes in output parameter
  98
  99 Arguments:
 100   This - Calling context
 101   Attributes - output buffer which contains attributes
 102
 103 Returns:
 104   EFI_INVALID_PARAMETER
 105   EFI_SUCCESS
 106
 107 --*/
 108 typedef
 109 EFI_STATUS
 110 (EFIAPI *FV_SET_ATTRIBUTES) (
 111   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 112   IN OUT EFI_FV_ATTRIBUTES          * Attributes
 113   );
 114
 115 /*++
 116
 117 Routine Description:
 118   Sets volume attributes
 119
 120 Arguments:
 121   This          Calling context
 122   Attributes    Buffer which contains attributes
 123
 124 Returns:
 125   EFI_INVALID_PARAMETER
 126   EFI_DEVICE_ERROR
 127   EFI_SUCCESS
 128
 129 --*/
 130
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI *FV_READ_FILE) (
 134   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 135   IN EFI_GUID                       * NameGuid,
 136   IN OUT VOID                       **Buffer,
 137   IN OUT UINTN                      *BufferSize,
 138   OUT EFI_FV_FILETYPE               * FoundType,
 139   OUT EFI_FV_FILE_ATTRIBUTES        * FileAttributes,
 140   OUT UINT32                        *AuthenticationStatus
 141   );
 142
 143 /*++
 144
 145 Routine Description:
 146     Read the requested file (NameGuid) and returns data in Buffer.
 147
 148 Arguments:
 149   This - Calling context
 150   NameGuid - Filename identifying which file to read
 151   Buffer - Pointer to pointer to buffer in which contents of file are returned.
 152
 153           If Buffer is NULL, only type, attributes, and size are returned as
 154           there is no output buffer.
 155
 156           If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 157           from BS pool by ReadFile
 158
 159           If Buffer != NULL and *Buffer != NULL, the output buffer has been
 160           allocated by the caller and is being passed in.
 161
 162   BufferSize - Indicates the buffer size passed in, and on output the size
 163           required to complete the read
 164   FoundType - Indicates the type of the file who's data is returned
 165   FileAttributes - Indicates the attributes of the file who's data is resturned
 166   AuthenticationStatus - Indicates the authentication status of the data
 167
 168 Returns:
 169   EFI_SUCCESS
 170   EFI_WARN_BUFFER_TOO_SMALL
 171   EFI_NOT_FOUND
 172   EFI_DEVICE_ERROR
 173   EFI_ACCESS_DENIED
 174
 175 --*/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *FV_READ_SECTION) (
 179   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 180   IN EFI_GUID                       * NameGuid,
 181   IN EFI_SECTION_TYPE               SectionType,
 182   IN UINTN                          SectionInstance,
 183   IN OUT VOID                       **Buffer,
 184   IN OUT UINTN                      *BufferSize,
 185   OUT UINT32                        *AuthenticationStatus
 186   );
 187
 188 /*++
 189
 190 Routine Description:
 191     Read the requested section from the specified file and returns data in Buffer.
 192
 193 Arguments:
 194   This - Calling context
 195   NameGuid - Filename identifying the file from which to read
 196   SectionType - Indicates what section type to retrieve
 197   SectionInstance - Indicates which instance of SectionType to retrieve
 198   Buffer - Pointer to pointer to buffer in which contents of file are returned.
 199
 200           If Buffer is NULL, only type, attributes, and size are returned as
 201           there is no output buffer.
 202
 203           If Buffer != NULL and *Buffer == NULL, the output buffer is allocated
 204           from BS pool by ReadFile
 205
 206           If Buffer != NULL and *Buffer != NULL, the output buffer has been
 207           allocated by the caller and is being passed in.
 208
 209   BufferSize - Indicates the buffer size passed in, and on output the size
 210           required to complete the read
 211   AuthenticationStatus - Indicates the authentication status of the data
 212
 213 Returns:
 214   EFI_SUCCESS
 215   EFI_WARN_BUFFER_TOO_SMALL
 216   EFI_OUT_OF_RESOURCES
 217   EFI_NOT_FOUND
 218   EFI_DEVICE_ERROR
 219   EFI_ACCESS_DENIED
 220
 221 --*/
 222
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *FV_WRITE_FILE) (
 226   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 227   IN UINT32                         NumberOfFiles,
 228   IN EFI_FV_WRITE_POLICY            WritePolicy,
 229   IN EFI_FV_WRITE_FILE_DATA         * FileData
 230   );
 231
 232 /*++
 233
 234 Routine Description:
 235   Write the supplied file (NameGuid) to the FV.
 236
 237 Arguments:
 238   This - Calling context
 239   NumberOfFiles - Indicates the number of file records pointed to by FileData
 240   WritePolicy - Indicates the level of reliability of the write with respect to
 241           things like power failure events.
 242   FileData - A pointer to an array of EFI_FV_WRITE_FILE_DATA structures.  Each
 243           element in the array indicates a file to write, and there are
 244           NumberOfFiles elements in the input array.
 245
 246 Returns:
 247   EFI_SUCCESS
 248   EFI_OUT_OF_RESOURCES
 249   EFI_DEVICE_ERROR
 250   EFI_WRITE_PROTECTED
 251   EFI_NOT_FOUND
 252   EFI_INVALID_PARAMETER
 253
 254 --*/
 255 typedef
 256 EFI_STATUS
 257 (EFIAPI *FV_GET_NEXT_FILE) (
 258   IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
 259   IN OUT VOID                       *Key,
 260   IN OUT EFI_FV_FILETYPE            * FileType,
 261   OUT EFI_GUID                      * NameGuid,
 262   OUT EFI_FV_FILE_ATTRIBUTES        * Attributes,
 263   OUT UINTN                         *Size
 264   );
 265
 266 /*++
 267
 268 Routine Description:
 269   Given the input key, search for the next matching file in the volume.
 270
 271 Arguments:
 272   This - Calling context
 273   Key - Pointer to a caller allocated buffer that contains an implementation
 274         specific key that is used to track where to begin searching on
 275         successive calls.
 276   FileType - Indicates the file type to filter for
 277   NameGuid - Guid filename of the file found
 278   Attributes - Attributes of the file found
 279   Size - Size in bytes of the file found
 280
 281 Returns:
 282   EFI_SUCCESS
 283   EFI_NOT_FOUND
 284   EFI_DEVICE_ERROR
 285   EFI_ACCESS_DENIED
 286
 287 --*/
 288 typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL {
 289   FV_GET_ATTRIBUTES GetVolumeAttributes;
 290   FV_SET_ATTRIBUTES SetVolumeAttributes;
 291   FV_READ_FILE      ReadFile;
 292   FV_READ_SECTION   ReadSection;
 293   FV_WRITE_FILE     WriteFile;
 294   FV_GET_NEXT_FILE  GetNextFile;
 295   UINT32            KeySize;
 296   EFI_HANDLE        ParentHandle;
 297 } EFI_FIRMWARE_VOLUME_PROTOCOL;
 298
 299 extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
 300
 301 #endif