Add more comments for PeiCore.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5618 6f19259b-4bc3-4df7-8a09-765794883524

MdeModulePkg/Core/Pei/FwVol/FwVol.c

@@ -108,7 +108,9 @@ CalculateHeaderChecksum (
   @param FileHandle      Handle of file image
   @param VolumeHandle    Handle of FV
 
-  @return EDES_TODO: Add description for return value
+  @retval TRUE  Success to find FV and return FV handle that contains file by given
+                file name.
+  @retval FALSE Can not find the FV that contains file by given file name.
 
 **/
 BOOLEAN
@@ -315,10 +317,9 @@ PeiInitializeFv (
 /**
   Process Firmware Volum Information once FvInfoPPI install.
 
-
+  @param PeiServices       An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.
-  @param PeiServices     - General purpose services available to every PEIM.
+  @param NotifyDescriptor  Address of the notification descriptor data structure.
-  @param NotifyDescriptor EDES_TODO: Add parameter description
+  @param Ppi               Address of the PPI that was installed.
-  @param Ppi             EDES_TODO: Add parameter description
 
   @retval EFI_SUCCESS if the interface could be successfully installed
 
@@ -407,14 +408,14 @@ FirmwareVolmeInfoPpiNotifyCallback (
   when meeting an encapsuled section.
 
 
-  @param PeiServices     - General purpose services available to every PEIM.
+  @param PeiServices     An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.
-                         SearchType   - Filter to find only section of this type.
+  @param SectionType     Filter to find only section of this type.
-  @param SectionType     EDES_TODO: Add parameter description
+  @param Section         From where to search.
-  @param Section         - From where to search.
+  @param SectionSize     The file size to search.
-  @param SectionSize     - The file size to search.
+  @param OutputBuffer    Pointer to the section to search.
-  @param OutputBuffer    - Pointer to the section to search.
 
-  @return EFI_STATUS
+  @retval EFI_NOT_FOUND Can not find the section by given section type.
+  @retval EFI_SUCCESS   Success to find the section and process section correctly.
 
 **/
 EFI_STATUS

MdeModulePkg/Core/Pei/PeiMain.h

@@ -275,9 +275,7 @@ PeimDispatchReadiness (
 /**
   Conduct PEIM dispatch.
 
-  @param SecCoreData     Points to a data structure containing information about the PEI core's operating
+  @param SecCoreData     Pointer to the data structure containing SEC to PEI handoff data
-                         environment, such as the size and location of temporary RAM, the stack location and
-                         the BFV location.
   @param PrivateData     Pointer to the private data passed in from caller
 
   @retval EFI_SUCCESS    Successfully dispatched PEIM.
@@ -317,10 +315,10 @@ InitializeDispatcherData (
 
   @param Private         PeiCore's private data structure
   @param FileHandle      PEIM's file handle
-  @param PeimCount       Peim count in all dispatched PEIMs.
+  @param PeimCount       The index of last dispatched PEIM.
 
-  @retval TRUE   Can be dispatched
+  @retval TRUE           Can be dispatched
-  @retval FALSE  Cannot be dispatched
+  @retval FALSE          Cannot be dispatched
 
 **/
 BOOLEAN
@@ -352,12 +350,13 @@ InitializePpiServices (
 
 /**
 
-  Convert Ppi description and PpiData pointer in heap after temporary memory
+  Migrate the Hob list from the CAR stack to PEI installed memory.
-  is migrated to permenent memory.
+
-  
+  @param PrivateData         Pointer to PeiCore's private data structure.
-  @param PrivateData         PeiCore's private data structure
+  @param OldCheckingBottom   Bottom of temporary memory range. All Ppi in this range
-  @param OldCheckingBottom   The old checking bottom.
+                             will be fixup for PpiData and PpiDescriptor pointer.
-  @param OldCheckingTop      The old checking top.
+  @param OldCheckingTop      Top of temporary memory range. All Ppi in this range
+                             will be fixup for PpiData and PpiDescriptor.
   @param Fixup               The address difference between
                              the new Hob list and old Hob list.
 
@@ -373,14 +372,14 @@ ConvertPpiPointers (
 
 /**
 
-  Install PPI services.
+  Install PPI services. It is implementation of EFI_PEI_SERVICE.InstallPpi.
 
   @param PeiServices                An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.
   @param PpiList                    Pointer to ppi array that want to be installed.
 
   @retval EFI_SUCCESS               if all PPIs in PpiList are successfully installed.
   @retval EFI_INVALID_PARAMETER     if PpiList is NULL pointer
-  @retval EFI_INVALID_PARAMETER     if any PPI in PpiList is not valid
+                                    if any PPI in PpiList is not valid
   @retval EFI_OUT_OF_RESOURCES      if there is no more memory resource to install PPI
 
 **/
@@ -402,7 +401,7 @@ PeiInstallPpi (
 
   @retval EFI_SUCCESS           if the operation was successful
   @retval EFI_INVALID_PARAMETER if OldPpi or NewPpi is NULL
-  @retval EFI_INVALID_PARAMETER if NewPpi is not valid
+                                if NewPpi is not valid
   @retval EFI_NOT_FOUND         if the PPI was not in the database
 
 **/
@@ -1060,7 +1059,7 @@ InitializeImageServices (
   @param PeiServices          An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.
   @param FileHandle           File handle of a Fv type file.
   @param AuthenticationState  Pointer to attestation authentication state of image.
-
+                              If return 0, means pass security checking.
 
   @retval EFI_NOT_FOUND       FV image can't be found.
   @retval EFI_SUCCESS         Successfully to process it.

MdeModulePkg/Core/Pei/PeiMain.inf

@@ -1,5 +1,8 @@
 #/** @file
-# Component description file for PeiMain module
+# PeiMain module is core module in PEI phase. It take reponsiblities of:
+# 1) Initialize memory, ppi, image services etc, to establish PEIM runtime environment.
+# 2) Dispatch PEIM from discoveried FV.
+# 3) Handoff control to DxeIpl to load dxe core and enter DXE phase.
 #
 # This module provide an DXE CIS compliant implementation.
 # Copyright (c) 2006 - 2007, Intel Corporation
@@ -93,5 +96,3 @@
 [FeaturePcd.common]
   gEfiMdeModulePkgTokenSpaceGuid.PcdPeiCoreImageLoaderSearchTeSectionFirst
 
-[BuildOptions.common]
-  MSFT:*_*_*_CC_FLAGS = /Fa$* /FAsc /FR$(@R).SBR

MdeModulePkg/Core/Pei/Ppi/Ppi.c

@@ -41,8 +41,10 @@ InitializePpiServices (
   Migrate the Hob list from the CAR stack to PEI installed memory.
 
   @param PrivateData         Pointer to PeiCore's private data structure.
-  @param OldCheckingBottom   The old checking bottom.
+  @param OldCheckingBottom   Bottom of temporary memory range. All Ppi in this range
-  @param OldCheckingTop      The old checking top.
+                             will be fixup for PpiData and PpiDescriptor pointer.
+  @param OldCheckingTop      Top of temporary memory range. All Ppi in this range
+                             will be fixup for PpiData and PpiDescriptor.
   @param Fixup               The address difference between
                              the new Hob list and old Hob list.
 
@@ -114,7 +116,7 @@ ConvertPpiPointers (
 
   @retval EFI_SUCCESS              if all PPIs in PpiList are successfully installed.
   @retval EFI_INVALID_PARAMETER    if PpiList is NULL pointer
-  @retval EFI_INVALID_PARAMETER    if any PPI in PpiList is not valid
+                                   if any PPI in PpiList is not valid
   @retval EFI_OUT_OF_RESOURCES     if there is no more memory resource to install PPI
 
 **/
@@ -147,7 +149,7 @@ PeiInstallPpi (
 
   for (;;) {
     //
-    // Since PpiData is used for NotifyList and InstallList, max resource
+    // Since PpiData is used for NotifyList and PpiList, max resource
     // is reached if the Install reaches the NotifyList
     //
     if (Index == PrivateData->PpiData.NotifyListEnd + 1) {