3 Copyright (c) 2004 - 2007, Intel Corporation. All rights reserved.<BR>
4 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 These functions assist in parsing and manipulating a Firmware Volume.
26 #include "CommonLib.h"
27 #include "EfiUtilityMsgs.h"
30 // Module global variables
32 EFI_FIRMWARE_VOLUME_HEADER
*mFvHeader
= NULL
;
36 // External function implementations
47 This initializes the FV lib with a pointer to the FV and length. It does not
48 verify the FV in any way.
52 Fv Buffer containing the FV.
53 FvLength Length of the FV
57 EFI_SUCCESS Function Completed successfully.
58 EFI_INVALID_PARAMETER A required parameter was NULL.
63 // Verify input arguments
66 return EFI_INVALID_PARAMETER
;
69 mFvHeader
= (EFI_FIRMWARE_VOLUME_HEADER
*) Fv
;
77 OUT EFI_FIRMWARE_VOLUME_HEADER
**FvHeader
,
84 This function returns a pointer to the current FV and the size.
88 FvHeader Pointer to the FV buffer.
89 FvLength Length of the FV
93 EFI_SUCCESS Function Completed successfully.
94 EFI_INVALID_PARAMETER A required parameter was NULL.
95 EFI_ABORTED The library needs to be initialized.
100 // Verify library has been initialized.
102 if (mFvHeader
== NULL
|| mFvLength
== 0) {
106 // Verify input arguments
108 if (FvHeader
== NULL
) {
109 return EFI_INVALID_PARAMETER
;
112 *FvHeader
= mFvHeader
;
118 IN EFI_FFS_FILE_HEADER
*CurrentFile
,
119 OUT EFI_FFS_FILE_HEADER
**NextFile
125 This function returns the next file. If the current file is NULL, it returns
126 the first file in the FV. If the function returns EFI_SUCCESS and the file
127 pointer is NULL, then there are no more files in the FV.
131 CurrentFile Pointer to the current file, must be within the current FV.
132 NextFile Pointer to the next file in the FV.
136 EFI_SUCCESS Function completed successfully.
137 EFI_INVALID_PARAMETER A required parameter was NULL or is out of range.
138 EFI_ABORTED The library needs to be initialized.
145 // Verify library has been initialized.
147 if (mFvHeader
== NULL
|| mFvLength
== 0) {
151 // Verify input arguments
153 if (NextFile
== NULL
) {
154 return EFI_INVALID_PARAMETER
;
159 Status
= VerifyFv (mFvHeader
);
160 if (EFI_ERROR (Status
)) {
166 if (CurrentFile
== NULL
) {
167 CurrentFile
= (EFI_FFS_FILE_HEADER
*) ((UINTN
) mFvHeader
+ mFvHeader
->HeaderLength
);
170 // Verify file is valid
172 Status
= VerifyFfsFile (CurrentFile
);
173 if (EFI_ERROR (Status
)) {
175 // no files in this FV
181 // Verify file is in this FV.
183 if ((UINTN
) CurrentFile
+ GetLength (CurrentFile
->Size
) > (UINTN
) mFvHeader
+ mFvLength
) {
188 *NextFile
= CurrentFile
;
193 // Verify current file is in range
195 if (((UINTN
) CurrentFile
< (UINTN
) mFvHeader
+ mFvHeader
->HeaderLength
) ||
196 ((UINTN
) CurrentFile
+ GetLength (CurrentFile
->Size
) > (UINTN
) mFvHeader
+ mFvLength
)
198 return EFI_INVALID_PARAMETER
;
201 // Get next file, compensate for 8 byte alignment if necessary.
203 *NextFile
= (EFI_FFS_FILE_HEADER
*) (((UINTN
) CurrentFile
+ GetLength (CurrentFile
->Size
) + 0x07) & (-1 << 3));
206 // Verify file is in this FV.
208 if (((UINTN
) *NextFile
+ sizeof (EFI_FFS_FILE_HEADER
) >= (UINTN
) mFvHeader
+ mFvLength
) ||
209 ((UINTN
) *NextFile
+ GetLength ((*NextFile
)->Size
) > (UINTN
) mFvHeader
+ mFvLength
)
215 // Verify file is valid
217 Status
= VerifyFfsFile (*NextFile
);
218 if (EFI_ERROR (Status
)) {
220 // no more files in this FV
231 IN EFI_GUID
*FileName
,
232 OUT EFI_FFS_FILE_HEADER
**File
238 Find a file by name. The function will return NULL if the file is not found.
242 FileName The GUID file name of the file to search for.
243 File Return pointer. In the case of an error, contents are undefined.
247 EFI_SUCCESS The function completed successfully.
248 EFI_ABORTED An error was encountered.
249 EFI_INVALID_PARAMETER One of the parameters was NULL.
253 EFI_FFS_FILE_HEADER
*CurrentFile
;
257 // Verify library has been initialized.
259 if (mFvHeader
== NULL
|| mFvLength
== 0) {
263 // Verify input parameters
265 if (FileName
== NULL
|| File
== NULL
) {
266 return EFI_INVALID_PARAMETER
;
271 Status
= VerifyFv (mFvHeader
);
272 if (EFI_ERROR (Status
)) {
276 // Get the first file
278 Status
= GetNextFile (NULL
, &CurrentFile
);
279 if (EFI_ERROR (Status
)) {
280 Error (NULL
, 0, 0, "error parsing the FV", NULL
);
284 // Loop as long as we have a valid file
286 while (CurrentFile
) {
287 if (!CompareGuid (&CurrentFile
->Name
, FileName
)) {
292 Status
= GetNextFile (CurrentFile
, &CurrentFile
);
293 if (EFI_ERROR (Status
)) {
294 Error (NULL
, 0, 0, "error parsing the FV", NULL
);
299 // File not found in this FV.
307 IN EFI_FV_FILETYPE FileType
,
309 OUT EFI_FFS_FILE_HEADER
**File
315 Find a file by type and instance. An instance of 1 is the first instance.
316 The function will return NULL if a matching file cannot be found.
317 File type EFI_FV_FILETYPE_ALL means any file type is valid.
321 FileType Type of file to search for.
322 Instance Instace of the file type to return.
323 File Return pointer. In the case of an error, contents are undefined.
327 EFI_SUCCESS The function completed successfully.
328 EFI_ABORTED An error was encountered.
329 EFI_INVALID_PARAMETER One of the parameters was NULL.
333 EFI_FFS_FILE_HEADER
*CurrentFile
;
338 // Verify library has been initialized.
340 if (mFvHeader
== NULL
|| mFvLength
== 0) {
344 // Verify input parameters
347 return EFI_INVALID_PARAMETER
;
352 Status
= VerifyFv (mFvHeader
);
353 if (EFI_ERROR (Status
)) {
357 // Initialize the number of matching files found.
362 // Get the first file
364 Status
= GetNextFile (NULL
, &CurrentFile
);
365 if (EFI_ERROR (Status
)) {
366 Error (NULL
, 0, 0, "error parsing FV", NULL
);
370 // Loop as long as we have a valid file
372 while (CurrentFile
) {
373 if (FileType
== EFI_FV_FILETYPE_ALL
|| CurrentFile
->Type
== FileType
) {
377 if (FileCount
== Instance
) {
382 Status
= GetNextFile (CurrentFile
, &CurrentFile
);
383 if (EFI_ERROR (Status
)) {
384 Error (NULL
, 0, 0, "error parsing the FV", NULL
);
394 SearchSectionByType (
395 IN EFI_FILE_SECTION_POINTER FirstSection
,
397 IN EFI_SECTION_TYPE SectionType
,
398 IN OUT UINTN
*StartIndex
,
400 OUT EFI_FILE_SECTION_POINTER
*Section
406 Helper function to search a sequence of sections from the section pointed
407 by FirstSection to SearchEnd for the Instance-th section of type SectionType.
408 The current counter is saved in StartIndex and when the section is found, it's
409 saved in Section. GUID-defined sections, if special processing is not required,
410 are searched recursively in a depth-first manner.
414 FirstSection The first section to start searching from.
415 SearchEnd The end address to stop search.
416 SectionType The type of section to search.
417 StartIndex The current counter is saved.
418 Instance The requested n-th section number.
419 Section The found section returned.
423 EFI_SUCCESS The function completed successfully.
424 EFI_NOT_FOUND The section is not found.
427 EFI_FILE_SECTION_POINTER CurrentSection
;
428 EFI_FILE_SECTION_POINTER InnerSection
;
432 CurrentSection
= FirstSection
;
434 while ((UINTN
) CurrentSection
.CommonHeader
< (UINTN
) SearchEnd
) {
435 if (CurrentSection
.CommonHeader
->Type
== SectionType
) {
439 if (*StartIndex
== Instance
) {
440 *Section
= CurrentSection
;
444 // If the requesting section is not GUID-defined and
445 // we find a GUID-defined section that doesn't need
446 // special processing, go ahead to search the requesting
447 // section inside the GUID-defined section.
449 if (SectionType
!= EFI_SECTION_GUID_DEFINED
&&
450 CurrentSection
.CommonHeader
->Type
== EFI_SECTION_GUID_DEFINED
&&
451 !(CurrentSection
.GuidDefinedSection
->Attributes
& EFI_GUIDED_SECTION_PROCESSING_REQUIRED
)) {
452 InnerSection
.CommonHeader
= (EFI_COMMON_SECTION_HEADER
*)
453 ((UINTN
) CurrentSection
.CommonHeader
+ CurrentSection
.GuidDefinedSection
->DataOffset
);
454 SectionSize
= CurrentSection
.CommonHeader
->Size
[0] +
455 (CurrentSection
.CommonHeader
->Size
[1] << 8) +
456 (CurrentSection
.CommonHeader
->Size
[2] << 16);
457 Status
= SearchSectionByType (
459 (UINT8
*) ((UINTN
) CurrentSection
.CommonHeader
+ SectionSize
),
465 if (!EFI_ERROR (Status
)) {
470 // Find next section (including compensating for alignment issues.
472 CurrentSection
.CommonHeader
= (EFI_COMMON_SECTION_HEADER
*) ((((UINTN
) CurrentSection
.CommonHeader
) + GetLength (CurrentSection
.CommonHeader
->Size
) + 0x03) & (-1 << 2));
475 return EFI_NOT_FOUND
;
480 IN EFI_FFS_FILE_HEADER
*File
,
481 IN EFI_SECTION_TYPE SectionType
,
483 OUT EFI_FILE_SECTION_POINTER
*Section
489 Find a section in a file by type and instance. An instance of 1 is the first
490 instance. The function will return NULL if a matching section cannot be found.
491 GUID-defined sections, if special processing is not needed, are handled in a
496 File The file to search.
497 SectionType Type of file to search for.
498 Instance Instace of the section to return.
499 Section Return pointer. In the case of an error, contents are undefined.
503 EFI_SUCCESS The function completed successfully.
504 EFI_ABORTED An error was encountered.
505 EFI_INVALID_PARAMETER One of the parameters was NULL.
506 EFI_NOT_FOUND No found.
509 EFI_FILE_SECTION_POINTER CurrentSection
;
514 // Verify input parameters
516 if (File
== NULL
|| Instance
== 0) {
517 return EFI_INVALID_PARAMETER
;
522 Status
= VerifyFfsFile (File
);
523 if (EFI_ERROR (Status
)) {
524 Error (NULL
, 0, 0, "invalid FFS file", NULL
);
528 // Initialize the number of matching sections found.
533 // Get the first section
535 CurrentSection
.CommonHeader
= (EFI_COMMON_SECTION_HEADER
*) ((UINTN
) File
+ sizeof (EFI_FFS_FILE_HEADER
));
537 Status
= SearchSectionByType (
539 (UINT8
*) ((UINTN
) File
+ GetLength (File
->Size
)),
546 if (!EFI_ERROR (Status
)) {
552 (*Section
).Code16Section
= NULL
;
553 return EFI_NOT_FOUND
;
557 // will not parse compressed sections
561 IN EFI_FIRMWARE_VOLUME_HEADER
*FvHeader
567 Verify the current pointer points to a valid FV header.
571 FvHeader Pointer to an alleged FV file.
575 EFI_SUCCESS The FV header is valid.
576 EFI_VOLUME_CORRUPTED The FV header is not valid.
577 EFI_INVALID_PARAMETER A required parameter was NULL.
578 EFI_ABORTED Operation aborted.
585 // Verify input parameters
587 if (FvHeader
== NULL
) {
588 return EFI_INVALID_PARAMETER
;
591 if (FvHeader
->Signature
!= EFI_FVH_SIGNATURE
) {
592 Error (NULL
, 0, 0, "invalid FV header signature", NULL
);
593 return EFI_VOLUME_CORRUPTED
;
596 // Verify header checksum
598 Checksum
= CalculateSum16 ((UINT16
*) FvHeader
, FvHeader
->HeaderLength
/ sizeof (UINT16
));
601 Error (NULL
, 0, 0, "invalid FV header checksum", NULL
);
610 IN EFI_FFS_FILE_HEADER
*FfsHeader
616 Verify the current pointer points to a FFS file header.
620 FfsHeader Pointer to an alleged FFS file.
624 EFI_SUCCESS The Ffs header is valid.
625 EFI_NOT_FOUND This "file" is the beginning of free space.
626 EFI_VOLUME_CORRUPTED The Ffs header is not valid.
627 EFI_ABORTED The erase polarity is not known.
631 BOOLEAN ErasePolarity
;
633 EFI_FFS_FILE_HEADER BlankHeader
;
636 UINT32 OccupiedFileLength
;
639 UINT8 FileGuidString
[80];
641 #if (PI_SPECIFICATION_VERSION < 0x00010000)
642 EFI_FFS_FILE_TAIL
*Tail
;
646 // Verify library has been initialized.
648 if (mFvHeader
== NULL
|| mFvLength
== 0) {
654 Status
= VerifyFv (mFvHeader
);
655 if (EFI_ERROR (Status
)) {
659 // Get the erase polarity.
661 Status
= GetErasePolarity (&ErasePolarity
);
662 if (EFI_ERROR (Status
)) {
666 // Check if we have free space
669 memset (&BlankHeader
, -1, sizeof (EFI_FFS_FILE_HEADER
));
671 memset (&BlankHeader
, 0, sizeof (EFI_FFS_FILE_HEADER
));
674 if (memcmp (&BlankHeader
, FfsHeader
, sizeof (EFI_FFS_FILE_HEADER
)) == 0) {
675 return EFI_NOT_FOUND
;
678 // Convert the GUID to a string so we can at least report which file
679 // if we find an error.
681 PrintGuidToBuffer (&FfsHeader
->Name
, FileGuidString
, sizeof (FileGuidString
), TRUE
);
682 if (FfsHeader
->Attributes
& FFS_ATTRIB_TAIL_PRESENT
) {
683 TailSize
= sizeof (EFI_FFS_FILE_TAIL
);
688 // Verify file header checksum
690 SavedState
= FfsHeader
->State
;
691 FfsHeader
->State
= 0;
692 SavedChecksum
= FfsHeader
->IntegrityCheck
.Checksum
.File
;
693 FfsHeader
->IntegrityCheck
.Checksum
.File
= 0;
694 Checksum
= CalculateSum8 ((UINT8
*) FfsHeader
, sizeof (EFI_FFS_FILE_HEADER
));
695 FfsHeader
->State
= SavedState
;
696 FfsHeader
->IntegrityCheck
.Checksum
.File
= SavedChecksum
;
698 Error (NULL
, 0, 0, FileGuidString
, "invalid FFS file header checksum");
702 // Verify file checksum
704 if (FfsHeader
->Attributes
& FFS_ATTRIB_CHECKSUM
) {
706 // Verify file data checksum
708 FileLength
= GetLength (FfsHeader
->Size
);
709 OccupiedFileLength
= (FileLength
+ 0x07) & (-1 << 3);
710 Checksum
= CalculateSum8 ((UINT8
*) FfsHeader
, FileLength
- TailSize
);
711 Checksum
= (UINT8
) (Checksum
- FfsHeader
->State
);
713 Error (NULL
, 0, 0, FileGuidString
, "invalid FFS file checksum");
718 // File does not have a checksum
719 // Verify contents are 0x5A as spec'd
721 if (FfsHeader
->IntegrityCheck
.Checksum
.File
!= FFS_FIXED_CHECKSUM
) {
722 Error (NULL
, 0, 0, FileGuidString
, "invalid fixed FFS file header checksum");
726 #if (PI_SPECIFICATION_VERSION < 0x00010000)
728 // Check if the tail is present and verify it if it is.
730 if (FfsHeader
->Attributes
& FFS_ATTRIB_TAIL_PRESENT
) {
732 // Verify tail is complement of integrity check field in the header.
734 Tail
= (EFI_FFS_FILE_TAIL
*) ((UINTN
) FfsHeader
+ GetLength (FfsHeader
->Size
) - sizeof (EFI_FFS_FILE_TAIL
));
735 if (FfsHeader
->IntegrityCheck
.TailReference
!= (EFI_FFS_FILE_TAIL
)~(*Tail
)) {
736 Error (NULL
, 0, 0, FileGuidString
, "invalid FFS file tail");
746 UINT8
*ThreeByteLength
752 Converts a three byte length value into a UINT32.
756 ThreeByteLength Pointer to the first of the 3 byte length.
760 UINT32 Size of the section
766 if (ThreeByteLength
== NULL
) {
770 Length
= *((UINT32
*) ThreeByteLength
);
771 Length
= Length
& 0x00FFFFFF;
778 OUT BOOLEAN
*ErasePolarity
784 This function returns with the FV erase polarity. If the erase polarity
785 for a bit is 1, the function return TRUE.
789 ErasePolarity A pointer to the erase polarity.
793 EFI_SUCCESS The function completed successfully.
794 EFI_INVALID_PARAMETER One of the input parameters was invalid.
795 EFI_ABORTED Operation aborted.
802 // Verify library has been initialized.
804 if (mFvHeader
== NULL
|| mFvLength
== 0) {
810 Status
= VerifyFv (mFvHeader
);
811 if (EFI_ERROR (Status
)) {
815 // Verify input parameters.
817 if (ErasePolarity
== NULL
) {
818 return EFI_INVALID_PARAMETER
;
821 if (mFvHeader
->Attributes
& EFI_FVB_ERASE_POLARITY
) {
822 *ErasePolarity
= TRUE
;
824 *ErasePolarity
= FALSE
;
832 IN BOOLEAN ErasePolarity
,
833 IN EFI_FFS_FILE_HEADER
*FfsHeader
839 This function returns a the highest state bit in the FFS that is set.
840 It in no way validate the FFS file.
844 ErasePolarity The erase polarity for the file state bits.
845 FfsHeader Pointer to a FFS file.
849 UINT8 The hightest set state of the file.
856 FileState
= FfsHeader
->State
;
859 FileState
= (UINT8
)~FileState
;
863 while (HighestBit
!= 0 && (HighestBit
& FileState
) == 0) {