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 Implements read firmware file
26 Required Alignment Alignment Value in FFS Alignment Value in
27 (bytes) Attributes Field Firmware Volume Interfaces
42 UINT8 mFvAttributes
[] = {0, 4, 7, 9, 10, 12, 15, 16};
46 EFI_FV_FILE_ATTRIBUTES
47 FfsAttributes2FvFileAttributes (
48 IN EFI_FFS_FILE_ATTRIBUTES FfsAttributes
53 Convert the FFS File Attributes to FV File Attributes
56 FfsAttributes - The attributes of UINT8 type.
59 The attributes of EFI_FV_FILE_ATTRIBUTES
63 FfsAttributes
= (EFI_FFS_FILE_ATTRIBUTES
)((FfsAttributes
& FFS_ATTRIB_DATA_ALIGNMENT
) >> 3);
64 ASSERT (FfsAttributes
< 8);
66 return (EFI_FV_FILE_ATTRIBUTES
) mFvAttributes
[FfsAttributes
];
73 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
75 IN OUT EFI_FV_FILETYPE
*FileType
,
76 OUT EFI_GUID
*NameGuid
,
77 OUT EFI_FV_FILE_ATTRIBUTES
*Attributes
,
83 Given the input key, search for the next matching file in the volume.
86 This - Indicates the calling context.
87 FileType - FileType is a pointer to a caller allocated
88 EFI_FV_FILETYPE. The GetNextFile() API can filter it's
89 search for files based on the value of *FileType input.
90 A *FileType input of 0 causes GetNextFile() to search for
91 files of all types. If a file is found, the file's type
92 is returned in *FileType. *FileType is not modified if
94 Key - Key is a pointer to a caller allocated buffer that
95 contains implementation specific data that is used to
96 track where to begin the search for the next file.
97 The size of the buffer must be at least This->KeySize
98 bytes long. To reinitialize the search and begin from
99 the beginning of the firmware volume, the entire buffer
100 must be cleared to zero. Other than clearing the buffer
101 to initiate a new search, the caller must not modify the
102 data in the buffer between calls to GetNextFile().
103 NameGuid - NameGuid is a pointer to a caller allocated EFI_GUID.
104 If a file is found, the file's name is returned in
105 *NameGuid. *NameGuid is not modified if no file is
107 Attributes - Attributes is a pointer to a caller allocated
108 EFI_FV_FILE_ATTRIBUTES. If a file is found, the file's
109 attributes are returned in *Attributes. *Attributes is
110 not modified if no file is found.
111 Size - Size is a pointer to a caller allocated UINTN.
112 If a file is found, the file's size is returned in *Size.
113 *Size is not modified if no file is found.
116 EFI_SUCCESS - Successfully find the file.
117 EFI_DEVICE_ERROR - Device error.
118 EFI_ACCESS_DENIED - Fv could not read.
119 EFI_NOT_FOUND - No matching file found.
120 EFI_INVALID_PARAMETER - Invalid parameter
126 EFI_FV_ATTRIBUTES FvAttributes
;
127 EFI_FFS_FILE_HEADER
*FfsFileHeader
;
130 FFS_FILE_LIST_ENTRY
*FfsFileEntry
;
133 FvDevice
= FV_DEVICE_FROM_THIS (This
);
135 Status
= FvGetVolumeAttributes (This
, &FvAttributes
);
136 if (EFI_ERROR (Status
)){
141 // Check if read operation is enabled
143 if ((FvAttributes
& EFI_FV_READ_STATUS
) == 0) {
144 return EFI_ACCESS_DENIED
;
147 if (*FileType
> EFI_FV_FILETYPE_FIRMWARE_VOLUME_IMAGE
) {
149 // File type needs to be in 0 - 0x0B
151 return EFI_INVALID_PARAMETER
;
154 KeyValue
= (UINTN
*)Key
;
156 if (*KeyValue
== 0) {
158 // Search for 1st matching file
160 Link
= &FvDevice
->FfsFileListHeader
;
163 // Key is pointer to FFsFileEntry, so get next one
165 Link
= (LIST_ENTRY
*)(*KeyValue
);
168 if (Link
->ForwardLink
== &FvDevice
->FfsFileListHeader
) {
170 // Next is end of list so we did not find data
172 return EFI_NOT_FOUND
;
175 FfsFileEntry
= (FFS_FILE_LIST_ENTRY
*)Link
->ForwardLink
;
176 FfsFileHeader
= (EFI_FFS_FILE_HEADER
*)FfsFileEntry
->FfsHeader
;
181 *KeyValue
= (UINTN
)FfsFileEntry
;
183 if (FfsFileHeader
->Type
== EFI_FV_FILETYPE_FFS_PAD
) {
185 // we ignore pad files
190 if (*FileType
== 0) {
192 // Process all file types so we have a match
197 if (*FileType
== FfsFileHeader
->Type
) {
199 // Found a matching file type
207 // Return FileType, NameGuid, and Attributes
209 *FileType
= FfsFileHeader
->Type
;
210 CopyMem (NameGuid
, &FfsFileHeader
->Name
, sizeof (EFI_GUID
));
211 *Attributes
= FfsAttributes2FvFileAttributes (FfsFileHeader
->Attributes
);
214 // Read four bytes out of the 3 byte array and throw out extra data
216 FileLength
= *(UINT32
*)&FfsFileHeader
->Size
[0] & 0x00FFFFFF;
219 // we need to substract the header size
221 *Size
= FileLength
- sizeof(EFI_FFS_FILE_HEADER
);
223 if (FfsFileHeader
->Attributes
& FFS_ATTRIB_TAIL_PRESENT
) {
225 // If tail is present substract it's size;
227 *Size
-= sizeof(EFI_FFS_FILE_TAIL
);
237 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
238 IN EFI_GUID
*NameGuid
,
239 IN OUT VOID
**Buffer
,
240 IN OUT UINTN
*BufferSize
,
241 OUT EFI_FV_FILETYPE
*FoundType
,
242 OUT EFI_FV_FILE_ATTRIBUTES
*FileAttributes
,
243 OUT UINT32
*AuthenticationStatus
248 Locates a file in the firmware volume and
249 copies it to the supplied buffer.
252 This - Indicates the calling context.
253 NameGuid - Pointer to an EFI_GUID, which is the filename.
254 Buffer - Buffer is a pointer to pointer to a buffer in
255 which the file or section contents or are returned.
256 BufferSize - BufferSize is a pointer to caller allocated
257 UINTN. On input *BufferSize indicates the size
258 in bytes of the memory region pointed to by
259 Buffer. On output, *BufferSize contains the number
260 of bytes required to read the file.
261 FoundType - FoundType is a pointer to a caller allocated
262 EFI_FV_FILETYPE that on successful return from Read()
263 contains the type of file read. This output reflects
264 the file type irrespective of the value of the
266 FileAttributes - FileAttributes is a pointer to a caller allocated
267 EFI_FV_FILE_ATTRIBUTES. On successful return from
268 Read(), *FileAttributes contains the attributes of
270 AuthenticationStatus - AuthenticationStatus is a pointer to a caller
271 allocated UINTN in which the authentication status
274 EFI_SUCCESS - Successfully read to memory buffer.
275 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
276 EFI_NOT_FOUND - Not found.
277 EFI_DEVICE_ERROR - Device error.
278 EFI_ACCESS_DENIED - Could not read.
279 EFI_INVALID_PARAMETER - Invalid parameter.
280 EFI_OUT_OF_RESOURCES - Not enough buffer to be allocated.
286 EFI_GUID SearchNameGuid
;
287 EFI_FV_FILETYPE LocalFoundType
;
288 EFI_FV_FILE_ATTRIBUTES LocalAttributes
;
291 EFI_FFS_FILE_HEADER
*FfsHeader
;
292 UINTN InputBufferSize
;
294 if (NULL
== NameGuid
) {
295 return EFI_INVALID_PARAMETER
;
298 FvDevice
= FV_DEVICE_FROM_THIS (This
);
302 // Keep looking until we find the matching NameGuid.
303 // The Key is really an FfsFileEntry
305 FvDevice
->LastKey
= 0;
308 Status
= FvGetNextFile (
316 if (EFI_ERROR (Status
)) {
317 return EFI_NOT_FOUND
;
319 } while (!CompareGuid (&SearchNameGuid
, NameGuid
));
322 // Get a pointer to the header
324 FfsHeader
= FvDevice
->LastKey
->FfsHeader
;
327 // Remember callers buffer size
329 InputBufferSize
= *BufferSize
;
332 // Calculate return values
334 *FoundType
= FfsHeader
->Type
;
335 *FileAttributes
= FfsAttributes2FvFileAttributes (FfsHeader
->Attributes
);
336 *AuthenticationStatus
= 0;
337 *BufferSize
= FileSize
;
339 if (Buffer
== NULL
) {
341 // If Buffer is NULL, we only want to get the information colected so far
347 // Skip over file header
349 SrcPtr
= ((UINT8
*)FfsHeader
) + sizeof (EFI_FFS_FILE_HEADER
);
351 Status
= EFI_SUCCESS
;
352 if (*Buffer
== NULL
) {
354 // Caller passed in a pointer so allocate buffer for them
356 *Buffer
= CoreAllocateBootServicesPool (FileSize
);
357 if (*Buffer
== NULL
) {
358 return EFI_OUT_OF_RESOURCES
;
360 } else if (FileSize
> InputBufferSize
) {
362 // Callers buffer was not big enough
364 Status
= EFI_WARN_BUFFER_TOO_SMALL
;
365 FileSize
= InputBufferSize
;
369 // Copy data into callers buffer
371 CopyMem (*Buffer
, SrcPtr
, FileSize
);
380 IN EFI_FIRMWARE_VOLUME_PROTOCOL
*This
,
381 IN EFI_GUID
*NameGuid
,
382 IN EFI_SECTION_TYPE SectionType
,
383 IN UINTN SectionInstance
,
384 IN OUT VOID
**Buffer
,
385 IN OUT UINTN
*BufferSize
,
386 OUT UINT32
*AuthenticationStatus
391 Locates a section in a given FFS File and
392 copies it to the supplied buffer (not including section header).
395 This - Indicates the calling context.
396 NameGuid - Pointer to an EFI_GUID, which is the filename.
397 SectionType - Indicates the section type to return.
398 SectionInstance - Indicates which instance of sections with a type of
399 SectionType to return.
400 Buffer - Buffer is a pointer to pointer to a buffer in which
401 the file or section contents or are returned.
402 BufferSize - BufferSize is a pointer to caller allocated UINTN.
403 AuthenticationStatus -AuthenticationStatus is a pointer to a caller
404 allocated UINT32 in which the authentication status
408 EFI_SUCCESS - Successfully read the file section into buffer.
409 EFI_WARN_BUFFER_TOO_SMALL - Buffer too small.
410 EFI_NOT_FOUND - Section not found.
411 EFI_DEVICE_ERROR - Device error.
412 EFI_ACCESS_DENIED - Could not read.
413 EFI_INVALID_PARAMETER - Invalid parameter.
419 EFI_FV_FILETYPE FileType
;
420 EFI_FV_FILE_ATTRIBUTES FileAttributes
;
423 EFI_SECTION_EXTRACTION_PROTOCOL
*Sep
;
424 FFS_FILE_LIST_ENTRY
*FfsEntry
;
426 if (NULL
== NameGuid
|| Buffer
== NULL
) {
427 return EFI_INVALID_PARAMETER
;
430 FvDevice
= FV_DEVICE_FROM_THIS (This
);
433 // Read the whole file into buffer
436 Status
= FvReadFile (
439 (VOID
**)&FileBuffer
,
446 // Get the last key used by our call to FvReadFile as it is the FfsEntry for this file.
448 FfsEntry
= (FFS_FILE_LIST_ENTRY
*)FvDevice
->LastKey
;
450 if (EFI_ERROR (Status
)) {
455 // Check to see that the file actually HAS sections before we go any further.
457 if (FileType
== EFI_FV_FILETYPE_RAW
) {
458 Status
= EFI_NOT_FOUND
;
463 // Use FfsEntry to cache Section Extraction Protocol Inforomation
465 if (FfsEntry
->StreamHandle
== 0) {
467 // Located the protocol
469 Status
= CoreLocateProtocol (&gEfiSectionExtractionProtocolGuid
, NULL
, (VOID
**)&Sep
);
471 // Section Extraction Protocol is part of Dxe Core so this should never fail
473 ASSERT_EFI_ERROR (Status
);
475 Status
= Sep
->OpenSectionStream (
479 &FfsEntry
->StreamHandle
481 if (EFI_ERROR (Status
)) {
488 // Get cached copy of Sep
494 // If SectionType == 0 We need the whole section stream
496 Status
= Sep
->GetSection (
498 FfsEntry
->StreamHandle
,
499 (SectionType
== 0) ? NULL
: &SectionType
,
501 (SectionType
== 0) ? 0 : SectionInstance
,
508 // Close of stream defered to close of FfsHeader list to allow SEP to cache data
512 CoreFreePool (FileBuffer
);