1/*++
2
3Copyright (c) 2004, Intel Corporation. All rights reserved.<BR>
4This program and the accompanying materials
5are licensed and made available under the terms and conditions of the BSD License
6which accompanies this distribution.  The full text of the license may be found at
7http://opensource.org/licenses/bsd-license.php
8
9THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
11
12Module Name:
13
14  FirmwareVolume.h
15
16Abstract:
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//
82typedef struct _EFI_FIRMWARE_VOLUME_PROTOCOL  EFI_FIRMWARE_VOLUME_PROTOCOL;
83
84typedef
85EFI_STATUS
86(EFIAPI *FV_GET_ATTRIBUTES) (
87  IN  EFI_FIRMWARE_VOLUME_PROTOCOL  * This,
88  OUT EFI_FV_ATTRIBUTES             * Attributes
89  );
90
91/*++
92
93Routine Description:
94  Retrieves attributes, insures positive polarity of attribute bits, returns
95  resulting attributes in output parameter
96
97Arguments:
98  This - Calling context
99  Attributes - output buffer which contains attributes
100
101Returns:
102  EFI_INVALID_PARAMETER
103  EFI_SUCCESS
104
105--*/
106typedef
107EFI_STATUS
108(EFIAPI *FV_SET_ATTRIBUTES) (
109  IN EFI_FIRMWARE_VOLUME_PROTOCOL   * This,
110  IN OUT EFI_FV_ATTRIBUTES          * Attributes
111  );
112
113/*++
114
115Routine Description:
116  Sets volume attributes
117
118Arguments:
119  This          Calling context
120  Attributes    Buffer which contains attributes
121
122Returns:
123  EFI_INVALID_PARAMETER
124  EFI_DEVICE_ERROR
125  EFI_SUCCESS
126
127--*/
128
129typedef
130EFI_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
143Routine Description:
144    Read the requested file (NameGuid) and returns data in Buffer.
145
146Arguments:
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
166Returns:
167  EFI_SUCCESS
168  EFI_WARN_BUFFER_TOO_SMALL
169  EFI_NOT_FOUND
170  EFI_DEVICE_ERROR
171  EFI_ACCESS_DENIED
172
173--*/
174typedef
175EFI_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
188Routine Description:
189    Read the requested section from the specified file and returns data in Buffer.
190
191Arguments:
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
211Returns:
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
221typedef
222EFI_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
232Routine Description:
233  Write the supplied file (NameGuid) to the FV.
234
235Arguments:
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
244Returns:
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--*/
253typedef
254EFI_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
266Routine Description:
267  Given the input key, search for the next matching file in the volume.
268
269Arguments:
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
279Returns:
280  EFI_SUCCESS
281  EFI_NOT_FOUND
282  EFI_DEVICE_ERROR
283  EFI_ACCESS_DENIED
284
285--*/
286struct _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
297extern EFI_GUID gEfiFirmwareVolumeProtocolGuid;
298
299#endif
300