2 Firmware File System protocol. Layers on top of Firmware
3 Block protocol to produce a file abstraction of FV based files.
5 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
6 This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __FW_VOL_DRIVER_H_
17 #define __FW_VOL_DRIVER_H_
20 #define FV2_DEVICE_SIGNATURE SIGNATURE_32 ('_', 'F', 'V', '2')
23 // Used to track all non-deleted files
27 EFI_FFS_FILE_HEADER
*FfsHeader
;
29 } FFS_FILE_LIST_ENTRY
;
33 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
35 EFI_FIRMWARE_VOLUME2_PROTOCOL Fv
;
37 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
41 FFS_FILE_LIST_ENTRY
*LastKey
;
43 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 Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
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
70 Sets current attributes for volume
72 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
73 @param Attributes At input, contains attributes to be set. At output
74 contains new value of FV.
76 @retval EFI_UNSUPPORTED Could not be set.
81 FvSetVolumeAttributes (
82 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
83 IN OUT EFI_FV_ATTRIBUTES
*Attributes
88 Given the input key, search for the next matching file in the volume.
90 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
91 @param Key Key is a pointer to a caller allocated
92 buffer that contains implementation specific
93 data that is used to track where to begin
94 the search for the next file. The size of
95 the buffer must be at least This->KeySize
96 bytes long. To reinitialize the search and
97 begin from the beginning of the firmware
98 volume, the entire buffer must be cleared to
99 zero. Other than clearing the buffer to
100 initiate a new search, the caller must not
101 modify the data in the buffer between calls
103 @param FileType FileType is a pointer to a caller allocated
104 EFI_FV_FILETYPE. The GetNextFile() API can
105 filter it's search for files based on the
106 value of *FileType input. A *FileType input
107 of 0 causes GetNextFile() to search for
108 files of all types. If a file is found, the
109 file's type is returned in *FileType.
110 *FileType is not modified if no file is
112 @param NameGuid NameGuid is a pointer to a caller allocated
113 EFI_GUID. If a file is found, the file's
114 name is returned in *NameGuid. *NameGuid is
115 not modified if no file is found.
116 @param Attributes Attributes is a pointer to a caller
117 allocated EFI_FV_FILE_ATTRIBUTES. If a file
118 is found, the file's attributes are returned
119 in *Attributes. *Attributes is not modified
121 @param Size Size is a pointer to a caller allocated
122 UINTN. If a file is found, the file's size
123 is returned in *Size. *Size is not modified
126 @retval EFI_SUCCESS Successfully find the file.
127 @retval EFI_DEVICE_ERROR Device error.
128 @retval EFI_ACCESS_DENIED Fv could not read.
129 @retval EFI_NOT_FOUND No matching file found.
130 @retval EFI_INVALID_PARAMETER Invalid parameter
136 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
138 IN OUT EFI_FV_FILETYPE
*FileType
,
139 OUT EFI_GUID
*NameGuid
,
140 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
147 Locates a file in the firmware volume and
148 copies it to the supplied buffer.
150 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
151 @param NameGuid Pointer to an EFI_GUID, which is the
153 @param Buffer Buffer is a pointer to pointer to a buffer
154 in which the file or section contents or are
156 @param BufferSize BufferSize is a pointer to caller allocated
157 UINTN. On input *BufferSize indicates the
158 size in bytes of the memory region pointed
159 to by Buffer. On output, *BufferSize
160 contains the number of bytes required to
162 @param FoundType FoundType is a pointer to a caller allocated
163 EFI_FV_FILETYPE that on successful return
164 from Read() contains the type of file read.
165 This output reflects the file type
166 irrespective of the value of the SectionType
168 @param FileAttributes FileAttributes is a pointer to a caller
169 allocated EFI_FV_FILE_ATTRIBUTES. On
170 successful return from Read(),
171 *FileAttributes contains the attributes of
173 @param AuthenticationStatus AuthenticationStatus is a pointer to a
174 caller allocated UINTN in which the
175 authentication status is returned.
177 @retval EFI_SUCCESS Successfully read to memory buffer.
178 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
179 @retval EFI_NOT_FOUND Not found.
180 @retval EFI_DEVICE_ERROR Device error.
181 @retval EFI_ACCESS_DENIED Could not read.
182 @retval EFI_INVALID_PARAMETER Invalid parameter.
183 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
189 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
190 IN CONST EFI_GUID
*NameGuid
,
191 IN OUT VOID
**Buffer
,
192 IN OUT UINTN
*BufferSize
,
193 OUT EFI_FV_FILETYPE
*FoundType
,
194 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
195 OUT UINT32
*AuthenticationStatus
200 Locates a section in a given FFS File and
201 copies it to the supplied buffer (not including section header).
203 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
204 @param NameGuid Pointer to an EFI_GUID, which is the
206 @param SectionType Indicates the section type to return.
207 @param SectionInstance Indicates which instance of sections with a
208 type of SectionType to return.
209 @param Buffer Buffer is a pointer to pointer to a buffer
210 in which the file or section contents or are
212 @param BufferSize BufferSize is a pointer to caller allocated
214 @param AuthenticationStatus AuthenticationStatus is a pointer to a
215 caller allocated UINT32 in which the
216 authentication status is returned.
218 @retval EFI_SUCCESS Successfully read the file section into
220 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
221 @retval EFI_NOT_FOUND Section not found.
222 @retval EFI_DEVICE_ERROR Device error.
223 @retval EFI_ACCESS_DENIED Could not read.
224 @retval EFI_INVALID_PARAMETER Invalid parameter.
230 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
231 IN CONST EFI_GUID
*NameGuid
,
232 IN EFI_SECTION_TYPE SectionType
,
233 IN UINTN SectionInstance
,
234 IN OUT VOID
**Buffer
,
235 IN OUT UINTN
*BufferSize
,
236 OUT UINT32
*AuthenticationStatus
241 Writes one or more files to the firmware volume.
243 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
244 @param NumberOfFiles Number of files.
245 @param WritePolicy WritePolicy indicates the level of reliability
246 for the write in the event of a power failure or
247 other system failure during the write operation.
248 @param FileData FileData is an pointer to an array of
249 EFI_FV_WRITE_DATA. Each element of array
250 FileData represents a file to be written.
252 @retval EFI_SUCCESS Files successfully written to firmware volume
253 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
254 @retval EFI_DEVICE_ERROR Device error.
255 @retval EFI_WRITE_PROTECTED Write protected.
256 @retval EFI_NOT_FOUND Not found.
257 @retval EFI_INVALID_PARAMETER Invalid parameter.
258 @retval EFI_UNSUPPORTED This function not supported.
264 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
265 IN UINT32 NumberOfFiles
,
266 IN EFI_FV_WRITE_POLICY WritePolicy
,
267 IN EFI_FV_WRITE_FILE_DATA
*FileData
272 Return information of type InformationType for the requested firmware
275 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
276 @param InformationType InformationType for requested.
277 @param BufferSize On input, size of Buffer.On output, the amount of data
279 @param Buffer A poniter to the data buffer to return.
281 @retval EFI_SUCCESS Successfully got volume Information.
287 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
288 IN CONST EFI_GUID
*InformationType
,
289 IN OUT UINTN
*BufferSize
,
296 Set information of type InformationType for the requested firmware
299 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
300 @param InformationType InformationType for requested.
301 @param BufferSize On input, size of Buffer.On output, the amount of data
303 @param Buffer A poniter to the data buffer to return.
305 @retval EFI_SUCCESS Successfully set volume Information.
311 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
312 IN CONST EFI_GUID
*InformationType
,
314 IN CONST VOID
*Buffer
320 Check if a block of buffer is erased.
322 @param ErasePolarity Erase polarity attribute of the firmware volume
323 @param InBuffer The buffer to be checked
324 @param BufferSize Size of the buffer in bytes
326 @retval TRUE The block of buffer is erased
327 @retval FALSE The block of buffer is not erased
332 IN UINT8 ErasePolarity
,
339 Get the FFS file state by checking the highest bit set in the header's state field.
341 @param ErasePolarity Erase polarity attribute of the firmware volume
342 @param FfsHeader Points to the FFS file header
344 @return FFS File state
349 IN UINT8 ErasePolarity
,
350 IN EFI_FFS_FILE_HEADER
*FfsHeader
355 Set the FFS file state.
357 @param State The state to be set.
358 @param FfsHeader Points to the FFS file header
366 IN EFI_FFS_FILE_HEADER
*FfsHeader
371 Verify checksum of the firmware volume header.
373 @param FvHeader Points to the firmware volume header to be checked
375 @retval TRUE Checksum verification passed
376 @retval FALSE Checksum verification failed
380 VerifyFvHeaderChecksum (
381 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
386 Check if it's a valid FFS file header.
388 @param ErasePolarity Erase polarity attribute of the firmware volume
389 @param FfsHeader Points to the FFS file header to be checked
390 @param FileState FFS file state to be returned
392 @retval TRUE Valid FFS file header
393 @retval FALSE Invalid FFS file header
398 IN UINT8 ErasePolarity
,
399 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
400 OUT EFI_FFS_FILE_STATE
*FileState
405 Check if it's a valid FFS file.
406 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
408 @param ErasePolarity Erase polarity attribute of the firmware volume
409 @param FfsHeader Points to the FFS file to be checked
411 @retval TRUE Valid FFS file
412 @retval FALSE Invalid FFS file
417 IN UINT8 ErasePolarity
,
418 IN EFI_FFS_FILE_HEADER
*FfsHeader
423 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
424 copy the volume header into it.
426 @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
427 read the volume header
428 @param FwVolHeader Pointer to pointer to allocated buffer in which
429 the volume header is returned.
431 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
432 @retval EFI_SUCCESS Successfully read volume header to the allocated
438 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
439 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
445 Check if an FV is consistent and allocate cache for it.
447 @param FvDevice A pointer to the FvDevice to be checked.
449 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
450 @retval EFI_SUCCESS FV is consistent and cache is allocated.
451 @retval EFI_VOLUME_CORRUPTED File system is corrupted.
456 IN OUT FV_DEVICE
*FvDevice