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 - 2008, 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
;
48 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV2_DEVICE_SIGNATURE)
51 Retrieves attributes, insures positive polarity of attribute bits, returns
52 resulting attributes in output parameter.
54 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
55 @param Attributes output buffer which contains attributes.
57 @retval EFI_SUCCESS Successfully got volume attributes.
62 FvGetVolumeAttributes (
63 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
64 OUT EFI_FV_ATTRIBUTES
*Attributes
69 Sets current attributes for volume
71 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
72 @param Attributes At input, contains attributes to be set. At output
73 contains new value of FV.
75 @retval EFI_UNSUPPORTED Could not be set.
80 FvSetVolumeAttributes (
81 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
82 IN OUT EFI_FV_ATTRIBUTES
*Attributes
87 Given the input key, search for the next matching file in the volume.
89 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
90 @param Key Key is a pointer to a caller allocated
91 buffer that contains implementation specific
92 data that is used to track where to begin
93 the search for the next file. The size of
94 the buffer must be at least This->KeySize
95 bytes long. To reinitialize the search and
96 begin from the beginning of the firmware
97 volume, the entire buffer must be cleared to
98 zero. Other than clearing the buffer to
99 initiate a new search, the caller must not
100 modify the data in the buffer between calls
102 @param FileType FileType is a pointer to a caller allocated
103 EFI_FV_FILETYPE. The GetNextFile() API can
104 filter it's search for files based on the
105 value of *FileType input. A *FileType input
106 of 0 causes GetNextFile() to search for
107 files of all types. If a file is found, the
108 file's type is returned in *FileType.
109 *FileType is not modified if no file is
111 @param NameGuid NameGuid is a pointer to a caller allocated
112 EFI_GUID. If a file is found, the file's
113 name is returned in *NameGuid. *NameGuid is
114 not modified if no file is found.
115 @param Attributes Attributes is a pointer to a caller
116 allocated EFI_FV_FILE_ATTRIBUTES. If a file
117 is found, the file's attributes are returned
118 in *Attributes. *Attributes is not modified
120 @param Size Size is a pointer to a caller allocated
121 UINTN. If a file is found, the file's size
122 is returned in *Size. *Size is not modified
125 @retval EFI_SUCCESS Successfully find the file.
126 @retval EFI_DEVICE_ERROR Device error.
127 @retval EFI_ACCESS_DENIED Fv could not read.
128 @retval EFI_NOT_FOUND No matching file found.
129 @retval EFI_INVALID_PARAMETER Invalid parameter
135 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
137 IN OUT EFI_FV_FILETYPE
*FileType
,
138 OUT EFI_GUID
*NameGuid
,
139 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
146 Locates a file in the firmware volume and
147 copies it to the supplied buffer.
149 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
150 @param NameGuid Pointer to an EFI_GUID, which is the
152 @param Buffer Buffer is a pointer to pointer to a buffer
153 in which the file or section contents or are
155 @param BufferSize BufferSize is a pointer to caller allocated
156 UINTN. On input *BufferSize indicates the
157 size in bytes of the memory region pointed
158 to by Buffer. On output, *BufferSize
159 contains the number of bytes required to
161 @param FoundType FoundType is a pointer to a caller allocated
162 EFI_FV_FILETYPE that on successful return
163 from Read() contains the type of file read.
164 This output reflects the file type
165 irrespective of the value of the SectionType
167 @param FileAttributes FileAttributes is a pointer to a caller
168 allocated EFI_FV_FILE_ATTRIBUTES. On
169 successful return from Read(),
170 *FileAttributes contains the attributes of
172 @param AuthenticationStatus AuthenticationStatus is a pointer to a
173 caller allocated UINTN in which the
174 authentication status is returned.
176 @retval EFI_SUCCESS Successfully read to memory buffer.
177 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
178 @retval EFI_NOT_FOUND Not found.
179 @retval EFI_DEVICE_ERROR Device error.
180 @retval EFI_ACCESS_DENIED Could not read.
181 @retval EFI_INVALID_PARAMETER Invalid parameter.
182 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
188 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
189 IN CONST EFI_GUID
*NameGuid
,
190 IN OUT VOID
**Buffer
,
191 IN OUT UINTN
*BufferSize
,
192 OUT EFI_FV_FILETYPE
*FoundType
,
193 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
194 OUT UINT32
*AuthenticationStatus
199 Locates a section in a given FFS File and
200 copies it to the supplied buffer (not including section header).
202 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
203 @param NameGuid Pointer to an EFI_GUID, which is the
205 @param SectionType Indicates the section type to return.
206 @param SectionInstance Indicates which instance of sections with a
207 type of SectionType to return.
208 @param Buffer Buffer is a pointer to pointer to a buffer
209 in which the file or section contents or are
211 @param BufferSize BufferSize is a pointer to caller allocated
213 @param AuthenticationStatus AuthenticationStatus is a pointer to a
214 caller allocated UINT32 in which the
215 authentication status is returned.
217 @retval EFI_SUCCESS Successfully read the file section into
219 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
220 @retval EFI_NOT_FOUND Section not found.
221 @retval EFI_DEVICE_ERROR Device error.
222 @retval EFI_ACCESS_DENIED Could not read.
223 @retval EFI_INVALID_PARAMETER Invalid parameter.
229 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
230 IN CONST EFI_GUID
*NameGuid
,
231 IN EFI_SECTION_TYPE SectionType
,
232 IN UINTN SectionInstance
,
233 IN OUT VOID
**Buffer
,
234 IN OUT UINTN
*BufferSize
,
235 OUT UINT32
*AuthenticationStatus
240 Writes one or more files to the firmware volume.
242 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
243 @param NumberOfFiles Number of files.
244 @param WritePolicy WritePolicy indicates the level of reliability
245 for the write in the event of a power failure or
246 other system failure during the write operation.
247 @param FileData FileData is an pointer to an array of
248 EFI_FV_WRITE_DATA. Each element of array
249 FileData represents a file to be written.
251 @retval EFI_SUCCESS Files successfully written to firmware volume
252 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
253 @retval EFI_DEVICE_ERROR Device error.
254 @retval EFI_WRITE_PROTECTED Write protected.
255 @retval EFI_NOT_FOUND Not found.
256 @retval EFI_INVALID_PARAMETER Invalid parameter.
257 @retval EFI_UNSUPPORTED This function not supported.
263 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
264 IN UINT32 NumberOfFiles
,
265 IN EFI_FV_WRITE_POLICY WritePolicy
,
266 IN EFI_FV_WRITE_FILE_DATA
*FileData
271 Return information of type InformationType for the requested firmware
274 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
275 @param InformationType InformationType for requested.
276 @param BufferSize On input, size of Buffer.On output, the amount of data
278 @param Buffer A poniter to the data buffer to return.
280 @retval EFI_SUCCESS Successfully got volume Information.
286 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
287 IN CONST EFI_GUID
*InformationType
,
288 IN OUT UINTN
*BufferSize
,
295 Set information of type InformationType for the requested firmware
298 @param This Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
299 @param InformationType InformationType for requested.
300 @param BufferSize On input, size of Buffer.On output, the amount of data
302 @param Buffer A poniter to the data buffer to return.
304 @retval EFI_SUCCESS Successfully set volume Information.
310 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
311 IN CONST EFI_GUID
*InformationType
,
313 IN CONST VOID
*Buffer
319 Check if a block of buffer is erased.
321 @param ErasePolarity Erase polarity attribute of the firmware volume
322 @param InBuffer The buffer to be checked
323 @param BufferSize Size of the buffer in bytes
325 @retval TRUE The block of buffer is erased
326 @retval FALSE The block of buffer is not erased
331 IN UINT8 ErasePolarity
,
338 Get the FFS file state by checking the highest bit set in the header's state field.
340 @param ErasePolarity Erase polarity attribute of the firmware volume
341 @param FfsHeader Points to the FFS file header
343 @return FFS File state
348 IN UINT8 ErasePolarity
,
349 IN EFI_FFS_FILE_HEADER
*FfsHeader
354 Set the FFS file state.
356 @param State The state to be set.
357 @param FfsHeader Points to the FFS file header
365 IN EFI_FFS_FILE_HEADER
*FfsHeader
370 Verify checksum of the firmware volume header.
372 @param FvHeader Points to the firmware volume header to be checked
374 @retval TRUE Checksum verification passed
375 @retval FALSE Checksum verification failed
379 VerifyFvHeaderChecksum (
380 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
385 Check if it's a valid FFS file header.
387 @param ErasePolarity Erase polarity attribute of the firmware volume
388 @param FfsHeader Points to the FFS file header to be checked
389 @param FileState FFS file state to be returned
391 @retval TRUE Valid FFS file header
392 @retval FALSE Invalid FFS file header
397 IN UINT8 ErasePolarity
,
398 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
399 OUT EFI_FFS_FILE_STATE
*FileState
404 Check if it's a valid FFS file.
405 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
407 @param ErasePolarity Erase polarity attribute of the firmware volume
408 @param FfsHeader Points to the FFS file to be checked
410 @retval TRUE Valid FFS file
411 @retval FALSE Invalid FFS file
416 IN UINT8 ErasePolarity
,
417 IN EFI_FFS_FILE_HEADER
*FfsHeader
422 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
423 copy the volume header into it.
425 @param Fvb The FW_VOL_BLOCK_PROTOCOL instance from which to
426 read the volume header
427 @param FwVolHeader Pointer to pointer to allocated buffer in which
428 the volume header is returned.
430 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
431 @retval EFI_SUCCESS Successfully read volume header to the allocated
437 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
438 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
444 Check if an FV is consistent and allocate cache for it.
446 @param FvDevice A pointer to the FvDevice to be checked.
448 @retval EFI_OUT_OF_RESOURCES No enough buffer could be allocated.
449 @retval EFI_SUCCESS FV is consistent and cache is allocated.
450 @retval EFI_VOLUME_CORRUPTED File system is corrupted.
455 IN OUT FV_DEVICE
*FvDevice