3 Firmware File System protocol. Layers on top of Firmware
4 Block protocol to produce a file abstraction of FV based files.
6 Copyright (c) 2006 - 2008, Intel Corporation
7 All rights reserved. This program and the accompanying materials
8 are licensed and made available under the terms and conditions of the BSD License
9 which accompanies this distribution. The full text of the license may be found at
10 http://opensource.org/licenses/bsd-license.php
12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
17 #ifndef __FW_VOL_DRIVER_H_
18 #define __FW_VOL_DRIVER_H_
21 #define FV2_DEVICE_SIGNATURE EFI_SIGNATURE_32 ('_', 'F', 'V', '2')
24 // Used to track all non-deleted files
28 EFI_FFS_FILE_HEADER
*FfsHeader
;
30 } FFS_FILE_LIST_ENTRY
;
34 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
36 EFI_FIRMWARE_VOLUME2_PROTOCOL Fv
;
38 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
42 FFS_FILE_LIST_ENTRY
*LastKey
;
44 LIST_ENTRY FfsFileListHeader
;
49 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
52 Retrieves attributes, insures positive polarity of attribute bits, returns
53 resulting attributes in output parameter.
55 @param This Calling context
56 @param Attributes output buffer which contains attributes
58 @retval EFI_SUCCESS Successfully got volume attributes
63 FvGetVolumeAttributes (
64 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
65 OUT EFI_FV_ATTRIBUTES
*Attributes
71 Sets current attributes for volume
73 @param This Calling context
74 @param Attributes At input, contains attributes to be set. At output
75 contains new value of FV
77 @retval EFI_UNSUPPORTED Could not be set.
82 FvSetVolumeAttributes (
83 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
84 IN OUT EFI_FV_ATTRIBUTES
*Attributes
90 Given the input key, search for the next matching file in the volume.
92 @param This Indicates the calling context.
93 @param Key Key is a pointer to a caller allocated
94 buffer that contains implementation specific
95 data that is used to track where to begin
96 the search for the next file. The size of
97 the buffer must be at least This->KeySize
98 bytes long. To reinitialize the search and
99 begin from the beginning of the firmware
100 volume, the entire buffer must be cleared to
101 zero. Other than clearing the buffer to
102 initiate a new search, the caller must not
103 modify the data in the buffer between calls
105 @param FileType FileType is a pointer to a caller allocated
106 EFI_FV_FILETYPE. The GetNextFile() API can
107 filter it's search for files based on the
108 value of *FileType input. A *FileType input
109 of 0 causes GetNextFile() to search for
110 files of all types. If a file is found, the
111 file's type is returned in *FileType.
112 *FileType is not modified if no file is
114 @param NameGuid NameGuid is a pointer to a caller allocated
115 EFI_GUID. If a file is found, the file's
116 name is returned in *NameGuid. *NameGuid is
117 not modified if no file is found.
118 @param Attributes Attributes is a pointer to a caller
119 allocated EFI_FV_FILE_ATTRIBUTES. If a file
120 is found, the file's attributes are returned
121 in *Attributes. *Attributes is not modified
123 @param Size Size is a pointer to a caller allocated
124 UINTN. If a file is found, the file's size
125 is returned in *Size. *Size is not modified
128 @retval EFI_SUCCESS Successfully find the file.
129 @retval EFI_DEVICE_ERROR Device error.
130 @retval EFI_ACCESS_DENIED Fv could not read.
131 @retval EFI_NOT_FOUND No matching file found.
132 @retval EFI_INVALID_PARAMETER Invalid parameter
138 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
140 IN OUT EFI_FV_FILETYPE
*FileType
,
141 OUT EFI_GUID
*NameGuid
,
142 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
150 Locates a file in the firmware volume and
151 copies it to the supplied buffer.
153 @param This Indicates the calling context.
154 @param NameGuid Pointer to an EFI_GUID, which is the
156 @param Buffer Buffer is a pointer to pointer to a buffer
157 in which the file or section contents or are
159 @param BufferSize BufferSize is a pointer to caller allocated
160 UINTN. On input *BufferSize indicates the
161 size in bytes of the memory region pointed
162 to by Buffer. On output, *BufferSize
163 contains the number of bytes required to
165 @param FoundType FoundType is a pointer to a caller allocated
166 EFI_FV_FILETYPE that on successful return
167 from Read() contains the type of file read.
168 This output reflects the file type
169 irrespective of the value of the SectionType
171 @param FileAttributes FileAttributes is a pointer to a caller
172 allocated EFI_FV_FILE_ATTRIBUTES. On
173 successful return from Read(),
174 *FileAttributes contains the attributes of
176 @param AuthenticationStatus AuthenticationStatus is a pointer to a
177 caller allocated UINTN in which the
178 authentication status is returned.
180 @retval EFI_SUCCESS Successfully read to memory buffer.
181 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
182 @retval EFI_NOT_FOUND Not found.
183 @retval EFI_DEVICE_ERROR Device error.
184 @retval EFI_ACCESS_DENIED Could not read.
185 @retval EFI_INVALID_PARAMETER Invalid parameter.
186 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
192 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
193 IN CONST EFI_GUID
*NameGuid
,
194 IN OUT VOID
**Buffer
,
195 IN OUT UINTN
*BufferSize
,
196 OUT EFI_FV_FILETYPE
*FoundType
,
197 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
198 OUT UINT32
*AuthenticationStatus
204 Locates a section in a given FFS File and
205 copies it to the supplied buffer (not including section header).
207 @param This Indicates the calling context.
208 @param NameGuid Pointer to an EFI_GUID, which is the
210 @param SectionType Indicates the section type to return.
211 @param SectionInstance Indicates which instance of sections with a
212 type of SectionType to return.
213 @param Buffer Buffer is a pointer to pointer to a buffer
214 in which the file or section contents or are
216 @param BufferSize BufferSize is a pointer to caller allocated
218 @param AuthenticationStatus AuthenticationStatus is a pointer to a
219 caller allocated UINT32 in which the
220 authentication status is returned.
222 @retval EFI_SUCCESS Successfully read the file section into
224 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
225 @retval EFI_NOT_FOUND Section not found.
226 @retval EFI_DEVICE_ERROR Device error.
227 @retval EFI_ACCESS_DENIED Could not read.
228 @retval EFI_INVALID_PARAMETER Invalid parameter.
234 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
235 IN CONST EFI_GUID
*NameGuid
,
236 IN EFI_SECTION_TYPE SectionType
,
237 IN UINTN SectionInstance
,
238 IN OUT VOID
**Buffer
,
239 IN OUT UINTN
*BufferSize
,
240 OUT UINT32
*AuthenticationStatus
246 Writes one or more files to the firmware volume.
248 @param This Indicates the calling context.
249 @param NumberOfFiles Number of files.
250 @param WritePolicy WritePolicy indicates the level of reliability
251 for the write in the event of a power failure or
252 other system failure during the write operation.
253 @param FileData FileData is an pointer to an array of
254 EFI_FV_WRITE_DATA. Each element of array
255 FileData represents a file to be written.
257 @retval EFI_SUCCESS Files successfully written to firmware volume
258 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
259 @retval EFI_DEVICE_ERROR Device error.
260 @retval EFI_WRITE_PROTECTED Write protected.
261 @retval EFI_NOT_FOUND Not found.
262 @retval EFI_INVALID_PARAMETER Invalid parameter.
263 @retval EFI_UNSUPPORTED This function not supported.
269 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
270 IN UINT32 NumberOfFiles
,
271 IN EFI_FV_WRITE_POLICY WritePolicy
,
272 IN EFI_FV_WRITE_FILE_DATA
*FileData
278 Return information of type InformationType for the requested firmware
281 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
282 @param InformationType InformationType for requested.
283 @param BufferSize On input, size of Buffer.On output, the amount of data
285 @param Buffer A poniter to the data buffer to return.
287 @retval EFI_SUCCESS Successfully got volume Information.
293 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
294 IN CONST EFI_GUID
*InformationType
,
295 IN OUT UINTN
*BufferSize
,
303 Set information of type InformationType for the requested firmware
306 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
307 @param InformationType InformationType for requested.
308 @param BufferSize On input, size of Buffer.On output, the amount of data
310 @param Buffer A poniter to the data buffer to return.
312 @retval EFI_SUCCESS Successfully set volume Information.
318 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
319 IN CONST EFI_GUID
*InformationType
,
321 IN CONST VOID
*Buffer
329 EfiCheckSumUint8
= 0,
330 EfiCheckSumUint16
= 1,
331 EfiCheckSumUint32
= 2,
332 EfiCheckSumUint64
= 3,
333 EfiCheckSumMaximum
= 4
339 Check if a block of buffer is erased.
341 @param ErasePolarity Erase polarity attribute of the firmware volume
342 @param InBuffer The buffer to be checked
343 @param BufferSize Size of the buffer in bytes
345 @retval TRUE The block of buffer is erased
346 @retval FALSE The block of buffer is not erased
351 IN UINT8 ErasePolarity
,
359 Get the FFS file state by checking the highest bit set in the header's state field.
361 @param ErasePolarity Erase polarity attribute of the firmware volume
362 @param FfsHeader Points to the FFS file header
364 @return FFS File state
369 IN UINT8 ErasePolarity
,
370 IN EFI_FFS_FILE_HEADER
*FfsHeader
376 Set the FFS file state.
378 @param State The state to be set.
379 @param FfsHeader Points to the FFS file header
387 IN EFI_FFS_FILE_HEADER
*FfsHeader
393 Verify checksum of the firmware volume header.
395 @param FvHeader Points to the firmware volume header to be checked
397 @retval TRUE Checksum verification passed
398 @retval FALSE Checksum verification failed
402 VerifyFvHeaderChecksum (
403 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
409 Check if it's a valid FFS file header.
411 @param ErasePolarity Erase polarity attribute of the firmware volume
412 @param FfsHeader Points to the FFS file header to be checked
413 @param FileState FFS file state to be returned
415 @retval TRUE Valid FFS file header
416 @retval FALSE Invalid FFS file header
421 IN UINT8 ErasePolarity
,
422 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
423 OUT EFI_FFS_FILE_STATE
*FileState
429 Check if it's a valid FFS file.
430 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
432 @param ErasePolarity Erase polarity attribute of the firmware volume
433 @param FfsHeader Points to the FFS file to be checked
435 @retval TRUE Valid FFS file
436 @retval FALSE Invalid FFS file
441 IN UINT8 ErasePolarity
,
442 IN EFI_FFS_FILE_HEADER
*FfsHeader
448 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
449 copy the volume header into it.
451 @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
452 read the volume header
453 @param FwVolHeader Pointer to pointer to allocated buffer in which
454 the volume header is returned.
456 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
457 @retval EFI_SUCCESS Successfully read volume header to the allocated
463 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
464 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
471 Check if a FV is consistent and allocate cache
473 @param FvDevice pointer to the FvDevice to be checked.
475 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
476 @retval EFI_SUCCESS FV is consistent and cache is allocated.
477 @retval EFI_VOLUME_CORRUPTED File system is corrupted.
482 IN OUT FV_DEVICE
*FvDevice