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.
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)
54 FvGetVolumeAttributes (
55 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
56 OUT EFI_FV_ATTRIBUTES
*Attributes
61 Retrieves attributes, insures positive polarity of attribute bits, returns
62 resulting attributes in output parameter
65 This - Calling context
66 Attributes - output buffer which contains attributes
69 EFI_SUCCESS - Successfully got volume attributes
76 FvSetVolumeAttributes (
77 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
78 IN OUT EFI_FV_ATTRIBUTES
*Attributes
83 Sets current attributes for volume
86 This - Calling context
87 Attributes - At input, contains attributes to be set. At output contains
91 EFI_UNSUPPORTED - Could not be set.
98 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
100 IN OUT EFI_FV_FILETYPE
*FileType
,
101 OUT EFI_GUID
*NameGuid
,
102 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
108 Given the input key, search for the next matching file in the volume.
111 This - Indicates the calling context.
112 FileType - FileType is a pointer to a caller allocated
113 EFI_FV_FILETYPE. The GetNextFile() API can filter it's
114 search for files based on the value of *FileType input.
115 A *FileType input of 0 causes GetNextFile() to search for
116 files of all types. If a file is found, the file's type
117 is returned in *FileType. *FileType is not modified if
119 Key - Key is a pointer to a caller allocated buffer that
120 contains implementation specific data that is used to
121 track where to begin the search for the next file.
122 The size of the buffer must be at least This->KeySize
123 bytes long. To reinitialize the search and begin from
124 the beginning of the firmware volume, the entire buffer
125 must be cleared to zero. Other than clearing the buffer
126 to initiate a new search, the caller must not modify the
127 data in the buffer between calls to GetNextFile().
128 NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
129 If a file is found, the file's name is returned in
130 *NameGuid. *NameGuid is not modified if no file is
132 Attributes - Attributes is a pointer to a caller allocated
133 EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
134 attributes are returned in *Attributes. *Attributes is
135 not modified if no file is found.
136 Size - Size is a pointer to a caller allocated UINTN.
137 If a file is found, the file's size is returned in *Size.
138 *Size is not modified if no file is found.
141 EFI_SUCCESS - Successfully find the file.
142 EFI_DEVICE_ERROR - Device error.
143 EFI_ACCESS_DENIED - Fv could not read.
144 EFI_NOT_FOUND - No matching file found.
145 EFI_INVALID_PARAMETER - Invalid parameter
154 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
155 IN CONST EFI_GUID
*NameGuid
,
156 IN OUT VOID
**Buffer
,
157 IN OUT UINTN
*BufferSize
,
158 OUT EFI_FV_FILETYPE
*FoundType
,
159 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
160 OUT UINT32
*AuthenticationStatus
165 Locates a file in the firmware volume and
166 copies it to the supplied buffer.
169 This - Indicates the calling context.
170 NameGuid - Pointer to an EFI_GUID, which is the filename.
171 Buffer - Buffer is a pointer to pointer to a buffer in
172 which the file or section contents or are returned.
173 BufferSize - BufferSize is a pointer to caller allocated
174 UINTN. On input *BufferSize indicates the size
175 in bytes of the memory region pointed to by
176 Buffer. On output, *BufferSize contains the number
177 of bytes required to read the file.
178 FoundType - FoundType is a pointer to a caller allocated
179 EFI_FV_FILETYPE that on successful return from Read()
180 contains the type of file read. This output reflects
181 the file type irrespective of the value of the
183 FileAttributes - FileAttributes is a pointer to a caller allocated
184 EFI_FV_FILE_ATTRIBUTES. On successful return from
185 Read(), *FileAttributes contains the attributes of
187 AuthenticationStatus - AuthenticationStatus is a pointer to a caller
188 allocated UINTN in which the authentication status
191 EFI_SUCCESS - Successfully read to memory buffer.
192 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
193 EFI_NOT_FOUND - Not found.
194 EFI_DEVICE_ERROR - Device error.
195 EFI_ACCESS_DENIED - Could not read.
196 EFI_INVALID_PARAMETER - Invalid parameter.
197 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
205 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
206 IN CONST EFI_GUID
*NameGuid
,
207 IN EFI_SECTION_TYPE SectionType
,
208 IN UINTN SectionInstance
,
209 IN OUT VOID
**Buffer
,
210 IN OUT UINTN
*BufferSize
,
211 OUT UINT32
*AuthenticationStatus
216 Locates a section in a given FFS File and
217 copies it to the supplied buffer (not including section header).
220 This - Indicates the calling context.
221 NameGuid - Pointer to an EFI_GUID, which is the filename.
222 SectionType - Indicates the section type to return.
223 SectionInstance - Indicates which instance of sections with a type of
224 SectionType to return.
225 Buffer - Buffer is a pointer to pointer to a buffer in which
226 the file or section contents or are returned.
227 BufferSize - BufferSize is a pointer to caller allocated UINTN.
228 AuthenticationStatus -AuthenticationStatus is a pointer to a caller
229 allocated UINT32 in which the authentication status
233 EFI_SUCCESS - Successfully read the file section into buffer.
234 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
235 EFI_NOT_FOUND - Section not found.
236 EFI_DEVICE_ERROR - Device error.
237 EFI_ACCESS_DENIED - Could not read.
238 EFI_INVALID_PARAMETER - Invalid parameter.
246 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
247 IN UINT32 NumberOfFiles
,
248 IN EFI_FV_WRITE_POLICY WritePolicy
,
249 IN EFI_FV_WRITE_FILE_DATA
*FileData
254 Writes one or more files to the firmware volume.
257 This - Indicates the calling context.
258 WritePolicy - WritePolicy indicates the level of reliability for
259 the write in the event of a power failure or other
260 system failure during the write operation.
261 FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
262 Each element of FileData[] represents a file to be written.
265 EFI_SUCCESS - Files successfully written to firmware volume
266 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
267 EFI_DEVICE_ERROR - Device error.
268 EFI_WRITE_PROTECTED - Write protected.
269 EFI_NOT_FOUND - Not found.
270 EFI_INVALID_PARAMETER - Invalid parameter.
271 EFI_UNSUPPORTED - This function not supported.
279 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
280 IN CONST EFI_GUID
*InformationType
,
281 IN OUT UINTN
*BufferSize
,
287 Return information of type InformationType for the requested firmware
291 This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
292 InformationType - InformationType for requested.
293 BufferSize - On input, size of Buffer.On output, the amount of
294 data returned in Buffer.
295 Buffer - A poniter to the data buffer to return.
297 EFI_SUCCESS - Successfully got volume Information.
306 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
307 IN CONST EFI_GUID
*InformationType
,
309 IN CONST VOID
*Buffer
314 Set information of type InformationType for the requested firmware
318 This - Pointer to EFI_FIRMWARE_VOLUME2_PROTOCOL.
319 InformationType - InformationType for requested.
320 BufferSize - On input, size of Buffer.On output, the amount of
321 data returned in Buffer.
322 Buffer - A poniter to the data buffer to return.
324 EFI_SUCCESS - Successfully set volume Information.
333 EfiCheckSumUint8
= 0,
334 EfiCheckSumUint16
= 1,
335 EfiCheckSumUint32
= 2,
336 EfiCheckSumUint64
= 3,
337 EfiCheckSumMaximum
= 4
343 IN UINT8 ErasePolarity
,
350 Check if a block of buffer is erased
353 ErasePolarity - Erase polarity attribute of the firmware volume
354 Buffer - The buffer to be checked
355 BufferSize - Size of the buffer in bytes
358 TRUE - The block of buffer is erased
359 FALSE - The block of buffer is not erased
366 IN UINT8 ErasePolarity
,
367 IN EFI_FFS_FILE_HEADER
*FfsHeader
372 Get the FFS file state by checking the highest bit set in the header's state field
375 ErasePolarity - Erase polarity attribute of the firmware volume
376 FfsHeader - Points to the FFS file header
387 IN EFI_FFS_FILE_HEADER
*FfsHeader
392 Set the FFS file state.
395 State - The state to be set.
396 FfsHeader - Points to the FFS file header
405 VerifyFvHeaderChecksum (
406 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
411 Verify checksum of the firmware volume header
414 FvHeader - Points to the firmware volume header to be checked
417 TRUE - Checksum verification passed
418 FALSE - Checksum verification failed
425 IN UINT8 ErasePolarity
,
426 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
427 OUT EFI_FFS_FILE_STATE
*FileState
432 Check if it's a valid FFS file header
435 ErasePolarity - Erase polarity attribute of the firmware volume
436 FfsHeader - Points to the FFS file header to be checked
437 FileState - FFS file state to be returned
440 TRUE - Valid FFS file header
441 FALSE - Invalid FFS file header
448 IN UINT8 ErasePolarity
,
449 IN EFI_FFS_FILE_HEADER
*FfsHeader
454 Check if it's a valid FFS file.
455 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
458 ErasePolarity - Erase polarity attribute of the firmware volume
459 FfsHeader - Points to the FFS file to be checked
462 TRUE - Valid FFS file
463 FALSE - Invalid FFS file
470 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
471 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
476 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
477 copy the volume header into it.
480 Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
482 FwVolHeader - Pointer to pointer to allocated buffer in which the volume
494 IN OUT FV_DEVICE
*FvDevice
499 Check if a FV is consistent and allocate cache
502 FvDevice - pointer to the FvDevice to be checked.
505 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
506 EFI_SUCCESS - FV is consistent and cache is allocated.
507 EFI_VOLUME_CORRUPTED - File system is corrupted.