/** @file\r
-\r
+ Pei Core Firmware File System service routines.\r
+ \r
Copyright (c) 2006 - 2007, Intel Corporation \r
All rights reserved. This program and the accompanying materials \r
are licensed and made available under the terms and conditions of the BSD License \r
\r
Abstract:\r
\r
- Pei Core Firmware File System service routines.\r
+ \r
\r
**/\r
\r
#define GET_OCCUPIED_SIZE(ActualSize, Alignment) \\r
(ActualSize) + (((Alignment) - ((ActualSize) & ((Alignment) - 1))) & ((Alignment) - 1))\r
\r
-STATIC\r
-EFI_FFS_FILE_STATE\r
-GetFileState(\r
- IN UINT8 ErasePolarity,\r
- IN EFI_FFS_FILE_HEADER *FfsHeader\r
- )\r
-/*++\r
-\r
-Routine Description:\r
-\r
+/**\r
Returns the highest bit set of the State field\r
\r
-Arguments:\r
\r
- ErasePolarity - Erase Polarity as defined by EFI_FVB2_ERASE_POLARITY\r
- in the Attributes field.\r
- FfsHeader - Pointer to FFS File Header.\r
+ @param ErasePolarity Erase Polarity as defined by EFI_FVB2_ERASE_POLARITY\r
+ in the Attributes field.\r
+ @param FfsHeader Pointer to FFS File Header.\r
\r
-Returns:\r
- Returns the highest bit in the State field\r
+ @return Returns the highest bit in the State field\r
\r
---*/\r
+**/\r
+EFI_FFS_FILE_STATE\r
+GetFileState(\r
+ IN UINT8 ErasePolarity,\r
+ IN EFI_FFS_FILE_HEADER *FfsHeader\r
+ )\r
{\r
EFI_FFS_FILE_STATE FileState;\r
EFI_FFS_FILE_STATE HighestBit;\r
return HighestBit;\r
} \r
\r
-STATIC\r
+/**\r
+ Calculates the checksum of the header of a file.\r
+\r
+ @param FileHeader Pointer to FFS File Header.\r
+\r
+ @return Checksum of the header.\r
+ The header is zero byte checksum.\r
+ Zero means the header is good.\r
+ Non-zero means the header is bad.\r
+**/\r
UINT8\r
CalculateHeaderChecksum (\r
IN EFI_FFS_FILE_HEADER *FileHeader\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Calculates the checksum of the header of a file.\r
-\r
-Arguments:\r
-\r
- FileHeader - Pointer to FFS File Header.\r
-\r
-Returns:\r
- Checksum of the header.\r
- \r
- The header is zero byte checksum.\r
- - Zero means the header is good.\r
- - Non-zero means the header is bad.\r
- \r
- \r
-Bugbug: For PEI performance reason, we comments this code at this time.\r
---*/\r
{\r
- UINT8 *ptr;\r
+ UINT8 *Ptr;\r
UINTN Index;\r
UINT8 Sum;\r
\r
Sum = 0;\r
- ptr = (UINT8 *)FileHeader;\r
+ Ptr = (UINT8 *)FileHeader;\r
\r
for (Index = 0; Index < sizeof(EFI_FFS_FILE_HEADER) - 3; Index += 4) {\r
- Sum = (UINT8)(Sum + ptr[Index]);\r
- Sum = (UINT8)(Sum + ptr[Index+1]);\r
- Sum = (UINT8)(Sum + ptr[Index+2]);\r
- Sum = (UINT8)(Sum + ptr[Index+3]);\r
+ Sum = (UINT8)(Sum + Ptr[Index]);\r
+ Sum = (UINT8)(Sum + Ptr[Index+1]);\r
+ Sum = (UINT8)(Sum + Ptr[Index+2]);\r
+ Sum = (UINT8)(Sum + Ptr[Index+3]);\r
}\r
\r
for (; Index < sizeof(EFI_FFS_FILE_HEADER); Index++) {\r
- Sum = (UINT8)(Sum + ptr[Index]);\r
+ Sum = (UINT8)(Sum + Ptr[Index]);\r
}\r
\r
//\r
return Sum;\r
}\r
\r
-STATIC\r
+/**\r
+ Find FV handler according some FileHandle in that FV.\r
+\r
+ @param FileHandle Handle of file image\r
+ @param VolumeHandle Handle of FV\r
+\r
+ @return EDES_TODO: Add description for return value\r
+\r
+**/\r
BOOLEAN\r
EFIAPI\r
PeiFileHandleToVolume (\r
return FALSE;\r
}\r
\r
+/**\r
+ Given the input file pointer, search for the next matching file in the\r
+ FFS volume as defined by SearchType. The search starts from FileHeader inside\r
+ the Firmware Volume defined by FwVolHeader.\r
+\r
+\r
+ @param FvHandle Pointer to the FV header of the volume to search\r
+ @param FileName File name\r
+ @param SearchType Filter to find only files of this type.\r
+ Type EFI_FV_FILETYPE_ALL causes no filtering to be done.\r
+ @param FileHandle This parameter must point to a valid FFS volume.\r
+ @param AprioriFile Pointer to AprioriFile image in this FV if has\r
\r
+ @return EFI_NOT_FOUND No files matching the search criteria were found\r
+ @retval EFI_SUCCESS Success to search given file\r
+\r
+**/\r
EFI_STATUS\r
PeiFindFileEx (\r
IN CONST EFI_PEI_FV_HANDLE FvHandle,\r
IN OUT EFI_PEI_FILE_HANDLE *FileHandle,\r
IN OUT EFI_PEI_FV_HANDLE *AprioriFile OPTIONAL\r
)\r
-/*++\r
-\r
-Routine Description:\r
- Given the input file pointer, search for the next matching file in the\r
- FFS volume as defined by SearchType. The search starts from FileHeader inside\r
- the Firmware Volume defined by FwVolHeader.\r
-\r
-Arguments:\r
- PeiServices - Pointer to the PEI Core Services Table.\r
- SearchType - Filter to find only files of this type.\r
- Type EFI_FV_FILETYPE_ALL causes no filtering to be done.\r
- FwVolHeader - Pointer to the FV header of the volume to search.\r
- This parameter must point to a valid FFS volume.\r
- FileHeader - Pointer to the current file from which to begin searching.\r
- This pointer will be updated upon return to reflect the file found.\r
- Flag - Indicator for if this is for PEI Dispath search \r
- \r
-Returns:\r
- EFI_NOT_FOUND - No files matching the search criteria were found\r
- EFI_SUCCESS\r
-\r
---*/\r
{\r
EFI_FIRMWARE_VOLUME_HEADER *FwVolHeader;\r
EFI_FFS_FILE_HEADER **FileHeader;\r
return EFI_NOT_FOUND; \r
}\r
\r
+/**\r
+\r
+ Initialize PeiCore Fv List.\r
+\r
+\r
+ @param PrivateData - Pointer to PEI_CORE_INSTANCE.\r
+ @param SecCoreData - Pointer to EFI_SEC_PEI_HAND_OFF.\r
+\r
+ @return NONE\r
+\r
+**/\r
VOID \r
PeiInitializeFv (\r
IN PEI_CORE_INSTANCE *PrivateData,\r
IN CONST EFI_SEC_PEI_HAND_OFF *SecCoreData\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Initialize PeiCore Fv List.\r
-\r
-Arguments:\r
- PrivateData - Pointer to PEI_CORE_INSTANCE.\r
- SecCoreData - Pointer to EFI_SEC_PEI_HAND_OFF.\r
-\r
-Returns:\r
- NONE \r
- \r
---*/ \r
{\r
EFI_STATUS Status;\r
//\r
\r
}\r
\r
+/**\r
+ Process Firmware Volum Information once FvInfoPPI install.\r
+\r
+\r
+ @param PeiServices - General purpose services available to every PEIM.\r
+ @param NotifyDescriptor EDES_TODO: Add parameter description\r
+ @param Ppi EDES_TODO: Add parameter description\r
+\r
+ @retval EFI_SUCCESS if the interface could be successfully installed\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
FirmwareVolmeInfoPpiNotifyCallback (\r
IN EFI_PEI_NOTIFY_DESCRIPTOR *NotifyDescriptor,\r
IN VOID *Ppi\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Process Firmware Volum Information once FvInfoPPI install.\r
-\r
-Arguments:\r
-\r
- PeiServices - General purpose services available to every PEIM.\r
- \r
-Returns:\r
-\r
- Status - EFI_SUCCESS if the interface could be successfully\r
- installed\r
-\r
---*/\r
{\r
UINT8 FvCount;\r
EFI_PEI_FIRMWARE_VOLUME_INFO_PPI *Fv;\r
return EFI_SUCCESS;\r
}\r
\r
+/**\r
+\r
+ Go through the file to search SectionType section,\r
+ when meeting an encapsuled section.\r
+\r
+\r
+ @param PeiServices - General purpose services available to every PEIM.\r
+ SearchType - Filter to find only section of this type.\r
+ @param SectionType EDES_TODO: Add parameter description\r
+ @param Section - From where to search.\r
+ @param SectionSize - The file size to search.\r
+ @param OutputBuffer - Pointer to the section to search.\r
+\r
+ @return EFI_STATUS\r
+\r
+**/\r
EFI_STATUS\r
PeiFfsProcessSection (\r
IN CONST EFI_PEI_SERVICES **PeiServices,\r
IN UINTN SectionSize,\r
OUT VOID **OutputBuffer\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Go through the file to search SectionType section,\r
- when meeting an encapsuled section. \r
- \r
-Arguments:\r
- PeiServices - General purpose services available to every PEIM.\r
- SearchType - Filter to find only section of this type.\r
- Section - From where to search.\r
- SectionSize - The file size to search.\r
- OutputBuffer - Pointer to the section to search.\r
-\r
-Returns:\r
- EFI_STATUS\r
- \r
---*/\r
{\r
EFI_STATUS Status;\r
UINT32 SectionLength;\r
}\r
\r
\r
+/**\r
+ Given the input file pointer, search for the next matching section in the\r
+ FFS volume.\r
+\r
+\r
+ @param PeiServices Pointer to the PEI Core Services Table.\r
+ @param SectionType Filter to find only sections of this type.\r
+ @param FileHandle Pointer to the current file to search.\r
+ @param SectionData Pointer to the Section matching SectionType in FfsFileHeader.\r
+ NULL if section not found\r
+\r
+ @retval EFI_NOT_FOUND No files matching the search criteria were found\r
+ @retval EFI_SUCCESS Success to find section data in given file\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
PeiFfsFindSectionData (\r
IN EFI_PEI_FILE_HANDLE FileHandle,\r
IN OUT VOID **SectionData\r
)\r
-/*++\r
-\r
-Routine Description:\r
- Given the input file pointer, search for the next matching section in the\r
- FFS volume.\r
-\r
-Arguments:\r
- PeiServices - Pointer to the PEI Core Services Table.\r
- SearchType - Filter to find only sections of this type.\r
- FfsFileHeader - Pointer to the current file to search.\r
- SectionData - Pointer to the Section matching SectionType in FfsFileHeader.\r
- - NULL if section not found\r
-\r
-Returns:\r
- EFI_NOT_FOUND - No files matching the search criteria were found\r
- EFI_SUCCESS\r
-\r
---*/\r
{\r
EFI_FFS_FILE_HEADER *FfsFileHeader;\r
UINT32 FileSize;\r
);\r
}\r
\r
+/**\r
+ Given the input file pointer, search for the next matching file in the\r
+ FFS volume as defined by SearchType. The search starts from FileHeader inside\r
+ the Firmware Volume defined by FwVolHeader.\r
\r
+\r
+ @param PeiServices Pointer to the PEI Core Services Table.\r
+ @param SearchType Filter to find only files of this type.\r
+ Type EFI_FV_FILETYPE_ALL causes no filtering to be done.\r
+ @param VolumeHandle Pointer to the FV header of the volume to search.\r
+ @param FileHandle Pointer to the current file from which to begin searching.\r
+ This pointer will be updated upon return to reflect the file found.\r
+ @retval EFI_NOT_FOUND No files matching the search criteria were found\r
+ @retval EFI_SUCCESS Success to find next file in given volume\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI\r
PeiFfsFindNextFile (\r
IN EFI_PEI_FV_HANDLE VolumeHandle,\r
IN OUT EFI_PEI_FILE_HANDLE *FileHandle\r
)\r
-/*++\r
-\r
-Routine Description:\r
- Given the input file pointer, search for the next matching file in the\r
- FFS volume as defined by SearchType. The search starts from FileHeader inside\r
- the Firmware Volume defined by FwVolHeader.\r
-\r
-Arguments:\r
- PeiServices - Pointer to the PEI Core Services Table.\r
- \r
- SearchType - Filter to find only files of this type.\r
- Type EFI_FV_FILETYPE_ALL causes no filtering to be done.\r
- \r
- FwVolHeader - Pointer to the FV header of the volume to search.\r
- This parameter must point to a valid FFS volume.\r
- \r
- FileHeader - Pointer to the current file from which to begin searching.\r
- This pointer will be updated upon return to reflect the file found.\r
- \r
-Returns:\r
- EFI_NOT_FOUND - No files matching the search criteria were found\r
- EFI_SUCCESS\r
-\r
---*/\r
{\r
return PeiFindFileEx (VolumeHandle, NULL, SearchType, FileHandle, NULL);\r
}\r
\r
\r
+/**\r
+ search the firmware volumes by index\r
+\r
+ @param PeiServices The PEI core services table.\r
+ @param Instance Instance of FV to find\r
+ @param VolumeHandle Pointer to found Volume.\r
+\r
+ @retval EFI_INVALID_PARAMETER FwVolHeader is NULL\r
+ @retval EFI_SUCCESS Firmware volume instance successfully found.\r
+\r
+**/\r
EFI_STATUS \r
EFIAPI\r
PeiFvFindNextVolume (\r
IN UINTN Instance,\r
IN OUT EFI_PEI_FV_HANDLE *VolumeHandle\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Return the firmware volumes.\r
-\r
- BugBug -- Move this to the location of this code to where the\r
- other FV and FFS support code lives.\r
- Also, update to use FindFV for instances #'s >= 1.\r
-\r
-Arguments:\r
-\r
- PeiServices - The PEI core services table.\r
- Instance - Instance of FV to find\r
- FwVolHeader - Pointer to contain the data to return\r
-\r
-Returns:\r
- Pointer to the Firmware Volume instance requested\r
-\r
- EFI_INVALID_PARAMETER - FwVolHeader is NULL\r
- \r
- EFI_SUCCESS - Firmware volume instance successfully found.\r
-\r
---*/\r
{\r
PEI_CORE_INSTANCE *Private;\r
\r
}\r
\r
\r
+/**\r
+\r
+ Given the input VolumeHandle, search for the next matching name file.\r
+\r
+\r
+ @param FileName - File name to search.\r
+ @param VolumeHandle - The current FV to search.\r
+ @param FileHandle - Pointer to the file matching name in VolumeHandle.\r
+ - NULL if file not found\r
+\r
+ @return EFI_STATUS\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI \r
PeiFfsFindFileByName (\r
IN EFI_PEI_FV_HANDLE VolumeHandle,\r
OUT EFI_PEI_FILE_HANDLE *FileHandle\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Given the input VolumeHandle, search for the next matching name file.\r
-\r
-Arguments:\r
-\r
- FileName - File name to search.\r
- VolumeHandle - The current FV to search.\r
- FileHandle - Pointer to the file matching name in VolumeHandle.\r
- - NULL if file not found\r
-Returns:\r
- EFI_STATUS\r
- \r
---*/ \r
{\r
EFI_STATUS Status;\r
if ((VolumeHandle == NULL) || (FileName == NULL) || (FileHandle == NULL)) {\r
return Status;\r
}\r
\r
+/**\r
+\r
+ Returns information about a specific file.\r
+\r
+\r
+ @param FileHandle - The handle to file.\r
+ @param FileInfo - Pointer to the file information.\r
+\r
+ @retval EFI_INVALID_PARAMETER Invalid FileHandle or FileInfo.\r
+ @retval EFI_SUCCESS Success to collect file info.\r
+\r
+**/\r
EFI_STATUS\r
EFIAPI \r
PeiFfsGetFileInfo (\r
IN EFI_PEI_FILE_HANDLE FileHandle,\r
OUT EFI_FV_FILE_INFO *FileInfo\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Collect information of given file.\r
-\r
-Arguments:\r
- FileHandle - The handle to file.\r
- FileInfo - Pointer to the file information.\r
-\r
-Returns:\r
- EFI_STATUS\r
- \r
---*/ \r
{\r
UINT8 FileState;\r
UINT8 ErasePolarity;\r
}\r
\r
\r
+/**\r
+\r
+ Collect information of given Fv Volume.\r
+\r
+ @param VolumeHandle - The handle to Fv Volume.\r
+ @param VolumeInfo - The pointer to volume information.\r
+\r
+ @retval EFI_INVALID_PARAMETER VolumeInfo is NULL\r
+ @retval EFI_SUCCESS Success to collect fv info.\r
+**/\r
EFI_STATUS\r
EFIAPI \r
PeiFfsGetVolumeInfo (\r
IN EFI_PEI_FV_HANDLE VolumeHandle,\r
OUT EFI_FV_INFO *VolumeInfo\r
)\r
-/*++\r
-\r
-Routine Description:\r
-\r
- Collect information of given Fv Volume.\r
-\r
-Arguments:\r
- VolumeHandle - The handle to Fv Volume.\r
- VolumeInfo - The pointer to volume information.\r
- \r
-Returns:\r
- EFI_STATUS\r
- \r
---*/ \r
{\r
EFI_FIRMWARE_VOLUME_HEADER FwVolHeader;\r
EFI_FIRMWARE_VOLUME_EXT_HEADER *FwVolExHeaderInfo;\r