3 Copyright (c) 2006, Intel Corporation
4 All rights reserved. This program and the accompanying materials
5 are licensed and made available under the terms and conditions of the BSD License
6 which accompanies this distribution. The full text of the license may be found at
7 http://opensource.org/licenses/bsd-license.php
9 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
10 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
18 Firmware File System protocol. Layers on top of Firmware
19 Block protocol to produce a file abstraction of FV based files.
28 // Used to track all non-deleted files
32 EFI_FFS_FILE_HEADER
*FfsHeader
;
34 EFI_SECTION_EXTRACTION_PROTOCOL
*Sep
;
35 } FFS_FILE_LIST_ENTRY
;
39 EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
;
41 EFI_FIRMWARE_VOLUME_PROTOCOL Fv
;
43 EFI_FIRMWARE_VOLUME_HEADER
*FwVolHeader
;
47 FFS_FILE_LIST_ENTRY
*LastKey
;
49 LIST_ENTRY FfsFileListHeader
;
54 #define FV_DEVICE_FROM_THIS(a) CR(a, FV_DEVICE, Fv, FV_DEVICE_SIGNATURE)
59 FvGetVolumeAttributes (
60 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
61 OUT EFI_FV_ATTRIBUTES
*Attributes
66 Retrieves attributes, insures positive polarity of attribute bits, returns
67 resulting attributes in output parameter
70 This - Calling context
71 Attributes - output buffer which contains attributes
74 EFI_SUCCESS - Successfully got volume attributes
81 FvSetVolumeAttributes (
82 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
83 IN OUT EFI_FV_ATTRIBUTES
*Attributes
88 Sets current attributes for volume
91 This - Calling context
92 Attributes - At input, contains attributes to be set. At output contains
96 EFI_UNSUPPORTED - Could not be set.
103 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
105 IN OUT EFI_FV_FILETYPE
*FileType
,
106 OUT EFI_GUID
*NameGuid
,
107 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
113 Given the input key, search for the next matching file in the volume.
116 This - Indicates the calling context.
117 FileType - FileType is a pointer to a caller allocated
118 EFI_FV_FILETYPE. The GetNextFile() API can filter it's
119 search for files based on the value of *FileType input.
120 A *FileType input of 0 causes GetNextFile() to search for
121 files of all types. If a file is found, the file's type
122 is returned in *FileType. *FileType is not modified if
124 Key - Key is a pointer to a caller allocated buffer that
125 contains implementation specific data that is used to
126 track where to begin the search for the next file.
127 The size of the buffer must be at least This->KeySize
128 bytes long. To reinitialize the search and begin from
129 the beginning of the firmware volume, the entire buffer
130 must be cleared to zero. Other than clearing the buffer
131 to initiate a new search, the caller must not modify the
132 data in the buffer between calls to GetNextFile().
133 NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
134 If a file is found, the file's name is returned in
135 *NameGuid. *NameGuid is not modified if no file is
137 Attributes - Attributes is a pointer to a caller allocated
138 EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
139 attributes are returned in *Attributes. *Attributes is
140 not modified if no file is found.
141 Size - Size is a pointer to a caller allocated UINTN.
142 If a file is found, the file's size is returned in *Size.
143 *Size is not modified if no file is found.
146 EFI_SUCCESS - Successfully find the file.
147 EFI_DEVICE_ERROR - Device error.
148 EFI_ACCESS_DENIED - Fv could not read.
149 EFI_NOT_FOUND - No matching file found.
150 EFI_INVALID_PARAMETER - Invalid parameter
159 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
160 IN EFI_GUID
*NameGuid
,
161 IN OUT VOID
**Buffer
,
162 IN OUT UINTN
*BufferSize
,
163 OUT EFI_FV_FILETYPE
*FoundType
,
164 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
165 OUT UINT32
*AuthenticationStatus
170 Locates a file in the firmware volume and
171 copies it to the supplied buffer.
174 This - Indicates the calling context.
175 NameGuid - Pointer to an EFI_GUID, which is the filename.
176 Buffer - Buffer is a pointer to pointer to a buffer in
177 which the file or section contents or are returned.
178 BufferSize - BufferSize is a pointer to caller allocated
179 UINTN. On input *BufferSize indicates the size
180 in bytes of the memory region pointed to by
181 Buffer. On output, *BufferSize contains the number
182 of bytes required to read the file.
183 FoundType - FoundType is a pointer to a caller allocated
184 EFI_FV_FILETYPE that on successful return from Read()
185 contains the type of file read. This output reflects
186 the file type irrespective of the value of the
188 FileAttributes - FileAttributes is a pointer to a caller allocated
189 EFI_FV_FILE_ATTRIBUTES. On successful return from
190 Read(), *FileAttributes contains the attributes of
192 AuthenticationStatus - AuthenticationStatus is a pointer to a caller
193 allocated UINTN in which the authentication status
196 EFI_SUCCESS - Successfully read to memory buffer.
197 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
198 EFI_NOT_FOUND - Not found.
199 EFI_DEVICE_ERROR - Device error.
200 EFI_ACCESS_DENIED - Could not read.
201 EFI_INVALID_PARAMETER - Invalid parameter.
202 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
210 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
211 IN EFI_GUID
*NameGuid
,
212 IN EFI_SECTION_TYPE SectionType
,
213 IN UINTN SectionInstance
,
214 IN OUT VOID
**Buffer
,
215 IN OUT UINTN
*BufferSize
,
216 OUT UINT32
*AuthenticationStatus
221 Locates a section in a given FFS File and
222 copies it to the supplied buffer (not including section header).
225 This - Indicates the calling context.
226 NameGuid - Pointer to an EFI_GUID, which is the filename.
227 SectionType - Indicates the section type to return.
228 SectionInstance - Indicates which instance of sections with a type of
229 SectionType to return.
230 Buffer - Buffer is a pointer to pointer to a buffer in which
231 the file or section contents or are returned.
232 BufferSize - BufferSize is a pointer to caller allocated UINTN.
233 AuthenticationStatus -AuthenticationStatus is a pointer to a caller
234 allocated UINT32 in which the authentication status
238 EFI_SUCCESS - Successfully read the file section into buffer.
239 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
240 EFI_NOT_FOUND - Section not found.
241 EFI_DEVICE_ERROR - Device error.
242 EFI_ACCESS_DENIED - Could not read.
243 EFI_INVALID_PARAMETER - Invalid parameter.
251 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
252 IN UINT32 NumberOfFiles
,
253 IN EFI_FV_WRITE_POLICY WritePolicy
,
254 IN EFI_FV_WRITE_FILE_DATA
*FileData
259 Writes one or more files to the firmware volume.
262 This - Indicates the calling context.
263 WritePolicy - WritePolicy indicates the level of reliability for
264 the write in the event of a power failure or other
265 system failure during the write operation.
266 FileData - FileData is an pointer to an array of EFI_FV_WRITE_DATA.
267 Each element of FileData[] represents a file to be written.
270 EFI_SUCCESS - Files successfully written to firmware volume
271 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
272 EFI_DEVICE_ERROR - Device error.
273 EFI_WRITE_PROTECTED - Write protected.
274 EFI_NOT_FOUND - Not found.
275 EFI_INVALID_PARAMETER - Invalid parameter.
276 EFI_UNSUPPORTED - This function not supported.
287 EfiCheckSumUint8
= 0,
288 EfiCheckSumUint16
= 1,
289 EfiCheckSumUint32
= 2,
290 EfiCheckSumUint64
= 3,
291 EfiCheckSumMaximum
= 4
297 IN UINT8 ErasePolarity
,
304 Check if a block of buffer is erased
307 ErasePolarity - Erase polarity attribute of the firmware volume
308 Buffer - The buffer to be checked
309 BufferSize - Size of the buffer in bytes
312 TRUE - The block of buffer is erased
313 FALSE - The block of buffer is not erased
320 IN UINT8 ErasePolarity
,
321 IN EFI_FFS_FILE_HEADER
*FfsHeader
326 Get the FFS file state by checking the highest bit set in the header's state field
329 ErasePolarity - Erase polarity attribute of the firmware volume
330 FfsHeader - Points to the FFS file header
341 IN EFI_FFS_FILE_HEADER
*FfsHeader
346 Set the FFS file state.
349 State - The state to be set.
350 FfsHeader - Points to the FFS file header
359 VerifyFvHeaderChecksum (
360 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
365 Verify checksum of the firmware volume header
368 FvHeader - Points to the firmware volume header to be checked
371 TRUE - Checksum verification passed
372 FALSE - Checksum verification failed
379 IN UINT8 ErasePolarity
,
380 IN EFI_FFS_FILE_HEADER
*FfsHeader
,
381 OUT EFI_FFS_FILE_STATE
*FileState
386 Check if it's a valid FFS file header
389 ErasePolarity - Erase polarity attribute of the firmware volume
390 FfsHeader - Points to the FFS file header to be checked
391 FileState - FFS file state to be returned
394 TRUE - Valid FFS file header
395 FALSE - Invalid FFS file header
402 IN UINT8 ErasePolarity
,
403 IN EFI_FFS_FILE_HEADER
*FfsHeader
408 Check if it's a valid FFS file.
409 Here we are sure that it has a valid FFS file header since we must call IsValidFfsHeader() first.
412 ErasePolarity - Erase polarity attribute of the firmware volume
413 FfsHeader - Points to the FFS file to be checked
416 TRUE - Valid FFS file
417 FALSE - Invalid FFS file
424 IN EFI_FIRMWARE_VOLUME_BLOCK_PROTOCOL
*Fvb
,
425 OUT EFI_FIRMWARE_VOLUME_HEADER
**FwVolHeader
430 given the supplied FW_VOL_BLOCK_PROTOCOL, allocate a buffer for output and
431 copy the volume header into it.
434 Fvb - The FW_VOL_BLOCK_PROTOCOL instance from which to read the volume
436 FwVolHeader - Pointer to pointer to allocated buffer in which the volume
448 IN OUT FV_DEVICE
*FvDevice
453 Check if a FV is consistent and allocate cache
456 FvDevice - pointer to the FvDevice to be checked.
459 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
460 EFI_SUCCESS - FV is consistent and cache is allocated.
461 EFI_VOLUME_CORRUPTED - File system is corrupted.