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, Intel Corporation
6 All rights reserved. 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.
20 #define FV2_DEVICE_SIGNATURE EFI_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)
53 FvGetVolumeAttributes (
54 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
55 OUT EFI_FV_ATTRIBUTES
*Attributes
60 Retrieves attributes, insures positive polarity of attribute bits, returns
61 resulting attributes in output parameter
64 This - Calling context
65 Attributes - output buffer which contains attributes
68 EFI_SUCCESS - Successfully got volume attributes
75 FvSetVolumeAttributes (
76 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
77 IN OUT EFI_FV_ATTRIBUTES
*Attributes
82 Sets current attributes for volume
85 This - Calling context
86 Attributes - At input, contains attributes to be set. At output contains
90 EFI_UNSUPPORTED - Could not be set.
97 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
99 IN OUT EFI_FV_FILETYPE
*FileType
,
100 OUT EFI_GUID
*NameGuid
,
101 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
107 Given the input key, search for the next matching file in the volume.
110 This - Indicates the calling context.
111 FileType - FileType is a pointer to a caller allocated
112 EFI_FV_FILETYPE. The GetNextFile() API can filter it's
113 search for files based on the value of *FileType input.
114 A *FileType input of 0 causes GetNextFile() to search for
115 files of all types. If a file is found, the file's type
116 is returned in *FileType. *FileType is not modified if
118 Key - Key is a pointer to a caller allocated buffer that
119 contains implementation specific data that is used to
120 track where to begin the search for the next file.
121 The size of the buffer must be at least This->KeySize
122 bytes long. To reinitialize the search and begin from
123 the beginning of the firmware volume, the entire buffer
124 must be cleared to zero. Other than clearing the buffer
125 to initiate a new search, the caller must not modify the
126 data in the buffer between calls to GetNextFile().
127 NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
128 If a file is found, the file's name is returned in
129 *NameGuid. *NameGuid is not modified if no file is
131 Attributes - Attributes is a pointer to a caller allocated
132 EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
133 attributes are returned in *Attributes. *Attributes is
134 not modified if no file is found.
135 Size - Size is a pointer to a caller allocated UINTN.
136 If a file is found, the file's size is returned in *Size.
137 *Size is not modified if no file is found.
140 EFI_SUCCESS - Successfully find the file.
141 EFI_DEVICE_ERROR - Device error.
142 EFI_ACCESS_DENIED - Fv could not read.
143 EFI_NOT_FOUND - No matching file found.
144 EFI_INVALID_PARAMETER - Invalid parameter
153 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
154 IN CONST EFI_GUID
*NameGuid
,
155 IN OUT VOID
**Buffer
,
156 IN OUT UINTN
*BufferSize
,
157 OUT EFI_FV_FILETYPE
*FoundType
,
158 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
159 OUT UINT32
*AuthenticationStatus
164 Locates a file in the firmware volume and
165 copies it to the supplied buffer.
168 This - Indicates the calling context.
169 NameGuid - Pointer to an EFI_GUID, which is the filename.
170 Buffer - Buffer is a pointer to pointer to a buffer in
171 which the file or section contents or are returned.
172 BufferSize - BufferSize is a pointer to caller allocated
173 UINTN. On input *BufferSize indicates the size
174 in bytes of the memory region pointed to by
175 Buffer. On output, *BufferSize contains the number
176 of bytes required to read the file.
177 FoundType - FoundType is a pointer to a caller allocated
178 EFI_FV_FILETYPE that on successful return from Read()
179 contains the type of file read. This output reflects
180 the file type irrespective of the value of the
182 FileAttributes - FileAttributes is a pointer to a caller allocated
183 EFI_FV_FILE_ATTRIBUTES. On successful return from
184 Read(), *FileAttributes contains the attributes of
186 AuthenticationStatus - AuthenticationStatus is a pointer to a caller
187 allocated UINTN in which the authentication status
190 EFI_SUCCESS - Successfully read to memory buffer.
191 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
192 EFI_NOT_FOUND - Not found.
193 EFI_DEVICE_ERROR - Device error.
194 EFI_ACCESS_DENIED - Could not read.
195 EFI_INVALID_PARAMETER - Invalid parameter.
196 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
204 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
205 IN CONST EFI_GUID
*NameGuid
,
206 IN EFI_SECTION_TYPE SectionType
,
207 IN UINTN SectionInstance
,
208 IN OUT VOID
**Buffer
,
209 IN OUT UINTN
*BufferSize
,
210 OUT UINT32
*AuthenticationStatus
215 Locates a section in a given FFS File and
216 copies it to the supplied buffer (not including section header).
219 This - Indicates the calling context.
220 NameGuid - Pointer to an EFI_GUID, which is the filename.
221 SectionType - Indicates the section type to return.
222 SectionInstance - Indicates which instance of sections with a type of
223 SectionType to return.
224 Buffer - Buffer is a pointer to pointer to a buffer in which
225 the file or section contents or are returned.
226 BufferSize - BufferSize is a pointer to caller allocated UINTN.
227 AuthenticationStatus -AuthenticationStatus is a pointer to a caller
228 allocated UINT32 in which the authentication status
232 EFI_SUCCESS - Successfully read the file section into buffer.
233 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
234 EFI_NOT_FOUND - Section not found.
235 EFI_DEVICE_ERROR - Device error.
236 EFI_ACCESS_DENIED - Could not read.
237 EFI_INVALID_PARAMETER - Invalid parameter.
245 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
246 IN UINT32 NumberOfFiles
,
247 IN EFI_FV_WRITE_POLICY WritePolicy
,
248 IN EFI_FV_WRITE_FILE_DATA
*FileData
253 Writes one or more files to the firmware volume.
256 This - Indicates the calling context.
257 WritePolicy - WritePolicy indicates the level of reliability for
258 the write in the event of a power failure or other
259 system failure during the write operation.
260 FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
261 Each element of FileData[] represents a file to be written.
264 EFI_SUCCESS - Files successfully written to firmware volume
265 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
266 EFI_DEVICE_ERROR - Device error.
267 EFI_WRITE_PROTECTED - Write protected.
268 EFI_NOT_FOUND - Not found.
269 EFI_INVALID_PARAMETER - Invalid parameter.
270 EFI_UNSUPPORTED - This function not supported.
278 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
279 IN CONST EFI_GUID
*InformationType
,
280 IN OUT UINTN
*BufferSize
,
286 Return information of type InformationType for the requested firmware
290 This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
291 InformationType - InformationType for requested.
292 BufferSize - On input, size of Buffer.On output, the amount of
293 data returned in Buffer.
294 Buffer - A poniter to the data buffer to return.
296 EFI_SUCCESS - Successfully got volume Information.
305 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
306 IN CONST EFI_GUID
*InformationType
,
308 IN CONST VOID
*Buffer
313 Set information of type InformationType for the requested firmware
317 This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
318 InformationType - InformationType for requested.
319 BufferSize - On input, size of Buffer.On output, the amount of
320 data returned in Buffer.
321 Buffer - A poniter to the data buffer to return.
323 EFI_SUCCESS - Successfully set volume Information.
332 EfiCheckSumUint8
= 0,
333 EfiCheckSumUint16
= 1,
334 EfiCheckSumUint32
= 2,
335 EfiCheckSumUint64
= 3,
336 EfiCheckSumMaximum
= 4
342 IN UINT8 ErasePolarity
,
349 Check if a block of buffer is erased
352 ErasePolarity - Erase polarity attribute of the firmware volume
353 Buffer - The buffer to be checked
354 BufferSize - Size of the buffer in bytes
357 TRUE - The block of buffer is erased
358 FALSE - The block of buffer is not erased
365 IN UINT8 ErasePolarity
,
366 IN EFI_FFS_FILE_HEADER
*FfsHeader
371 Get the FFS file state by checking the highest bit set in the header's state field
374 ErasePolarity - Erase polarity attribute of the firmware volume
375 FfsHeader - Points to the FFS file header
386 IN EFI_FFS_FILE_HEADER
*FfsHeader
391 Set the FFS file state.
394 State - The state to be set.
395 FfsHeader - Points to the FFS file header
404 VerifyFvHeaderChecksum (
405 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
410 Verify checksum of the firmware volume header
413 FvHeader - Points to the firmware volume header to be checked
416 TRUE - Checksum verification passed
417 FALSE - Checksum verification failed
424 IN UINT8 ErasePolarity
,
425 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
426 OUT EFI_FFS_FILE_STATE
*FileState
431 Check if it's a valid FFS file header
434 ErasePolarity - Erase polarity attribute of the firmware volume
435 FfsHeader - Points to the FFS file header to be checked
436 FileState - FFS file state to be returned
439 TRUE - Valid FFS file header
440 FALSE - Invalid FFS file header
447 IN UINT8 ErasePolarity
,
448 IN EFI_FFS_FILE_HEADER
*FfsHeader
453 Check if it's a valid FFS file.
454 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
457 ErasePolarity - Erase polarity attribute of the firmware volume
458 FfsHeader - Points to the FFS file to be checked
461 TRUE - Valid FFS file
462 FALSE - Invalid FFS file
469 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
470 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
475 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
476 copy the volume header into it.
479 Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
481 FwVolHeader - Pointer to pointer to allocated buffer in which the volume
493 IN OUT FV_DEVICE
*FvDevice
498 Check if a FV is consistent and allocate cache
501 FvDevice - pointer to the FvDevice to be checked.
504 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
505 EFI_SUCCESS - FV is consistent and cache is allocated.
506 EFI_VOLUME_CORRUPTED - File system is corrupted.