2 Implements functions to read firmware file
4 Copyright (c) 2006 - 2009, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #include "FwVolDriver.h"
19 Required Alignment Alignment Value in FFS Alignment Value in
20 (bytes) Attributes Field Firmware Volume Interfaces
33 UINT8 mFvAttributes
[] = {0, 4, 7, 9, 10, 12, 15, 16};
38 Convert the FFS File Attributes to FV File Attributes
40 @param FfsAttributes The attributes of UINT8 type.
42 @return The attributes of EFI_FV_FILE_ATTRIBUTES
45 EFI_FV_FILE_ATTRIBUTES
46 FfsAttributes2FvFileAttributes (
47 IN EFI_FFS_FILE_ATTRIBUTES FfsAttributes
50 FfsAttributes
= (EFI_FFS_FILE_ATTRIBUTES
)((FfsAttributes
& FFS_ATTRIB_DATA_ALIGNMENT
) >> 3);
51 ASSERT (FfsAttributes
< 8);
53 return (EFI_FV_FILE_ATTRIBUTES
) mFvAttributes
[FfsAttributes
];
59 Given the input key, search for the next matching file in the volume.
61 @param This Indicates the calling context.
62 @param Key Key is a pointer to a caller allocated
63 buffer that contains implementation specific
64 data that is used to track where to begin
65 the search for the next file. The size of
66 the buffer must be at least This->KeySize
67 bytes long. To reinitialize the search and
68 begin from the beginning of the firmware
69 volume, the entire buffer must be cleared to
70 zero. Other than clearing the buffer to
71 initiate a new search, the caller must not
72 modify the data in the buffer between calls
74 @param FileType FileType is a pointer to a caller allocated
75 EFI_FV_FILETYPE. The GetNextFile() API can
76 filter it's search for files based on the
77 value of *FileType input. A *FileType input
78 of 0 causes GetNextFile() to search for
79 files of all types. If a file is found, the
80 file's type is returned in *FileType.
81 *FileType is not modified if no file is
83 @param NameGuid NameGuid is a pointer to a caller allocated
84 EFI_GUID. If a file is found, the file's
85 name is returned in *NameGuid. *NameGuid is
86 not modified if no file is found.
87 @param Attributes Attributes is a pointer to a caller
88 allocated EFI_FV_FILE_ATTRIBUTES. If a file
89 is found, the file's attributes are returned
90 in *Attributes. *Attributes is not modified
92 @param Size Size is a pointer to a caller allocated
93 UINTN. If a file is found, the file's size
94 is returned in *Size. *Size is not modified
97 @retval EFI_SUCCESS Successfully find the file.
98 @retval EFI_DEVICE_ERROR Device error.
99 @retval EFI_ACCESS_DENIED Fv could not read.
100 @retval EFI_NOT_FOUND No matching file found.
101 @retval EFI_INVALID_PARAMETER Invalid parameter
107 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
109 IN OUT EFI_FV_FILETYPE
*FileType
,
110 OUT EFI_GUID
*NameGuid
,
111 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
117 EFI_FV_ATTRIBUTES FvAttributes
;
118 EFI_FFS_FILE_HEADER
*FfsFileHeader
;
121 FFS_FILE_LIST_ENTRY
*FfsFileEntry
;
124 FvDevice
= FV_DEVICE_FROM_THIS (This
);
126 Status
= FvGetVolumeAttributes (This
, &FvAttributes
);
127 if (EFI_ERROR (Status
)){
132 // Check if read operation is enabled
134 if ((FvAttributes
& EFI_FV2_READ_STATUS
) == 0) {
135 return EFI_ACCESS_DENIED
;
138 if (*FileType
> EFI_FV_FILETYPE_SMM_CORE
) {
140 // File type needs to be in 0 - 0x0D
142 return EFI_NOT_FOUND
;
145 KeyValue
= (UINTN
*)Key
;
147 if (*KeyValue
== 0) {
149 // Search for 1st matching file
151 Link
= &FvDevice
->FfsFileListHeader
;
154 // Key is pointer to FFsFileEntry, so get next one
156 Link
= (LIST_ENTRY
*)(*KeyValue
);
159 if (Link
->ForwardLink
== &FvDevice
->FfsFileListHeader
) {
161 // Next is end of list so we did not find data
163 return EFI_NOT_FOUND
;
166 FfsFileEntry
= (FFS_FILE_LIST_ENTRY
*)Link
->ForwardLink
;
167 FfsFileHeader
= (EFI_FFS_FILE_HEADER
*)FfsFileEntry
->FfsHeader
;
172 *KeyValue
= (UINTN
)FfsFileEntry
;
174 if (FfsFileHeader
->Type
== EFI_FV_FILETYPE_FFS_PAD
) {
176 // we ignore pad files
181 if (*FileType
== EFI_FV_FILETYPE_ALL
) {
183 // Process all file types so we have a match
188 if (*FileType
== FfsFileHeader
->Type
) {
190 // Found a matching file type
198 // Return FileType, NameGuid, and Attributes
200 *FileType
= FfsFileHeader
->Type
;
201 CopyGuid (NameGuid
, &FfsFileHeader
->Name
);
202 *Attributes
= FfsAttributes2FvFileAttributes (FfsFileHeader
->Attributes
);
205 // Read four bytes out of the 3 byte array and throw out extra data
207 FileLength
= *(UINT32
*)&FfsFileHeader
->Size
[0] & 0x00FFFFFF;
210 // we need to substract the header size
212 *Size
= FileLength
- sizeof(EFI_FFS_FILE_HEADER
);
220 Locates a file in the firmware volume and
221 copies it to the supplied buffer.
223 @param This Indicates the calling context.
224 @param NameGuid Pointer to an EFI_GUID, which is the
226 @param Buffer Buffer is a pointer to pointer to a buffer
227 in which the file or section contents or are
229 @param BufferSize BufferSize is a pointer to caller allocated
230 UINTN. On input *BufferSize indicates the
231 size in bytes of the memory region pointed
232 to by Buffer. On output, *BufferSize
233 contains the number of bytes required to
235 @param FoundType FoundType is a pointer to a caller allocated
236 EFI_FV_FILETYPE that on successful return
237 from Read() contains the type of file read.
238 This output reflects the file type
239 irrespective of the value of the SectionType
241 @param FileAttributes FileAttributes is a pointer to a caller
242 allocated EFI_FV_FILE_ATTRIBUTES. On
243 successful return from Read(),
244 *FileAttributes contains the attributes of
246 @param AuthenticationStatus AuthenticationStatus is a pointer to a
247 caller allocated UINTN in which the
248 authentication status is returned.
250 @retval EFI_SUCCESS Successfully read to memory buffer.
251 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
252 @retval EFI_NOT_FOUND Not found.
253 @retval EFI_DEVICE_ERROR Device error.
254 @retval EFI_ACCESS_DENIED Could not read.
255 @retval EFI_INVALID_PARAMETER Invalid parameter.
256 @retval EFI_OUT_OF_RESOURCES Not enough buffer to be allocated.
262 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
263 IN CONST EFI_GUID
*NameGuid
,
264 IN OUT VOID
**Buffer
,
265 IN OUT UINTN
*BufferSize
,
266 OUT EFI_FV_FILETYPE
*FoundType
,
267 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
268 OUT UINT32
*AuthenticationStatus
273 EFI_GUID SearchNameGuid
;
274 EFI_FV_FILETYPE LocalFoundType
;
275 EFI_FV_FILE_ATTRIBUTES LocalAttributes
;
278 EFI_FFS_FILE_HEADER
*FfsHeader
;
279 UINTN InputBufferSize
;
281 if (NameGuid
== NULL
) {
282 return EFI_INVALID_PARAMETER
;
285 FvDevice
= FV_DEVICE_FROM_THIS (This
);
289 // Keep looking until we find the matching NameGuid.
290 // The Key is really an FfsFileEntry
292 FvDevice
->LastKey
= 0;
295 Status
= FvGetNextFile (
303 if (EFI_ERROR (Status
)) {
304 return EFI_NOT_FOUND
;
306 } while (!CompareGuid (&SearchNameGuid
, NameGuid
));
309 // Get a pointer to the header
311 FfsHeader
= FvDevice
->LastKey
->FfsHeader
;
314 // Remember callers buffer size
316 InputBufferSize
= *BufferSize
;
319 // Calculate return values
321 *FoundType
= FfsHeader
->Type
;
322 *FileAttributes
= FfsAttributes2FvFileAttributes (FfsHeader
->Attributes
);
323 *AuthenticationStatus
= 0;
324 *BufferSize
= FileSize
;
326 if (Buffer
== NULL
) {
328 // If Buffer is NULL, we only want to get the information collected so far
334 // Skip over file header
336 SrcPtr
= ((UINT8
*)FfsHeader
) + sizeof (EFI_FFS_FILE_HEADER
);
338 Status
= EFI_SUCCESS
;
339 if (*Buffer
== NULL
) {
341 // Caller passed in a pointer so allocate buffer for them
343 *Buffer
= AllocatePool (FileSize
);
344 if (*Buffer
== NULL
) {
345 return EFI_OUT_OF_RESOURCES
;
347 } else if (FileSize
> InputBufferSize
) {
349 // Callers buffer was not big enough
351 Status
= EFI_WARN_BUFFER_TOO_SMALL
;
352 FileSize
= InputBufferSize
;
356 // Copy data into callers buffer
358 CopyMem (*Buffer
, SrcPtr
, FileSize
);
366 Locates a section in a given FFS File and
367 copies it to the supplied buffer (not including section header).
369 @param This Indicates the calling context.
370 @param NameGuid Pointer to an EFI_GUID, which is the
372 @param SectionType Indicates the section type to return.
373 @param SectionInstance Indicates which instance of sections with a
374 type of SectionType to return.
375 @param Buffer Buffer is a pointer to pointer to a buffer
376 in which the file or section contents or are
378 @param BufferSize BufferSize is a pointer to caller allocated
380 @param AuthenticationStatus AuthenticationStatus is a pointer to a
381 caller allocated UINT32 in which the
382 authentication status is returned.
384 @retval EFI_SUCCESS Successfully read the file section into
386 @retval EFI_WARN_BUFFER_TOO_SMALL Buffer too small.
387 @retval EFI_NOT_FOUND Section not found.
388 @retval EFI_DEVICE_ERROR Device error.
389 @retval EFI_ACCESS_DENIED Could not read.
390 @retval EFI_INVALID_PARAMETER Invalid parameter.
396 IN CONST EFI_FIRMWARE_VOLUME2_PROTOCOL
*This
,
397 IN CONST EFI_GUID
*NameGuid
,
398 IN EFI_SECTION_TYPE SectionType
,
399 IN UINTN SectionInstance
,
400 IN OUT VOID
**Buffer
,
401 IN OUT UINTN
*BufferSize
,
402 OUT UINT32
*AuthenticationStatus
407 EFI_FV_FILETYPE FileType
;
408 EFI_FV_FILE_ATTRIBUTES FileAttributes
;
411 FFS_FILE_LIST_ENTRY
*FfsEntry
;
413 if (NameGuid
== NULL
|| Buffer
== NULL
) {
414 return EFI_INVALID_PARAMETER
;
417 FvDevice
= FV_DEVICE_FROM_THIS (This
);
420 // Read the whole file into buffer
423 Status
= FvReadFile (
426 (VOID
**)&FileBuffer
,
433 // Get the last key used by our call to FvReadFile as it is the FfsEntry for this file.
435 FfsEntry
= (FFS_FILE_LIST_ENTRY
*) FvDevice
->LastKey
;
437 if (EFI_ERROR (Status
)) {
442 // Check to see that the file actually HAS sections before we go any further.
444 if (FileType
== EFI_FV_FILETYPE_RAW
) {
445 Status
= EFI_NOT_FOUND
;
450 // Use FfsEntry to cache Section Extraction Protocol Inforomation
452 if (FfsEntry
->StreamHandle
== 0) {
453 Status
= OpenSectionStream (
456 &FfsEntry
->StreamHandle
458 if (EFI_ERROR (Status
)) {
464 // If SectionType == 0 We need the whole section stream
466 Status
= GetSection (
467 FfsEntry
->StreamHandle
,
468 (SectionType
== 0) ? NULL
: &SectionType
,
470 (SectionType
== 0) ? 0 : SectionInstance
,
477 // Close of stream defered to close of FfsHeader list to allow SEP to cache data
481 CoreFreePool (FileBuffer
);