Correct more comments for PeiCore.

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

4 files changed, 71 insertions, 57 deletions

diff --git a/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c b/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c
index 9e0160cc86..1ea443f6ef 100644
--- a/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c
+++ b/MdeModulePkg/Core/Pei/Dispatcher/Dispatcher.c
@@ -100,7 +100,7 @@ DiscoverPeimsAndOrderWithApriori (
       Private->AprioriCount -= sizeof (EFI_FFS_FILE_HEADER) - sizeof (EFI_COMMON_SECTION_HEADER);

       Private->AprioriCount /= sizeof (EFI_GUID);

 

-      SetMem (FileGuid, sizeof (FileGuid), 0);

+      ZeroMem (FileGuid, sizeof (FileGuid));

       for (Index = 0; Index < PeimCount; Index++) {

         //

         // Make an array of file name guids that matches the FileHandle array so we can convert

@@ -178,6 +178,7 @@ DiscoverPeimsAndOrderWithApriori (
   @param PeiServices     An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

   @param PrivateInMem    PeiCore's private data structure

 

+  @return PeiCore function address after shadowing.

 **/

 VOID*

 ShadowPeiCore(

@@ -215,6 +216,10 @@ ShadowPeiCore(
               );

   ASSERT_EFI_ERROR (Status);

 

+  //

+  // Compute the PeiCore's function address after shaowed PeiCore.

+  // _ModuleEntryPoint is PeiCore main function entry

+  //

   return (VOID*) ((UINTN) EntryPoint + (UINTN) PeiCore - (UINTN) _ModuleEntryPoint);

 }

 

@@ -791,9 +796,11 @@ PeiRegisterForShadow (
   @param AuthenticationState  Pointer to attestation authentication state of image.

 

 

-  @retval EFI_NOT_FOUND       FV image can't be found.

-  @retval EFI_SUCCESS         Successfully to process it.

-

+  @retval EFI_NOT_FOUND         FV image can't be found.

+  @retval EFI_SUCCESS           Successfully to process it.

+  @retval EFI_OUT_OF_RESOURCES  Can not allocate page when aligning FV image

+  @retval Others                Can not find EFI_SECTION_FIRMWARE_VOLUME_IMAGE section

+  

 **/

 EFI_STATUS

 ProcessFvFile (

@@ -840,11 +847,13 @@ ProcessFvFile (
   if (EFI_ERROR (Status)) {

     return Status;

   }

+  

   //

   // Collect FvImage Info.

   //

   Status = PeiFfsGetVolumeInfo (FvImageHandle, &FvImageInfo);

   ASSERT_EFI_ERROR (Status);

+  

   //

   // FvAlignment must be more than 8 bytes required by FvHeader structure.

   //

@@ -852,6 +861,7 @@ ProcessFvFile (
   if (FvAlignment < 8) {

     FvAlignment = 8;

   }

+  

   //

   // Check FvImage

   //

diff --git a/MdeModulePkg/Core/Pei/Memory/MemoryServices.c b/MdeModulePkg/Core/Pei/Memory/MemoryServices.c
index d24897d776..7e841c3c46 100644
--- a/MdeModulePkg/Core/Pei/Memory/MemoryServices.c
+++ b/MdeModulePkg/Core/Pei/Memory/MemoryServices.c
@@ -18,8 +18,7 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 

   Initialize the memory services.

 

-

-  @param PrivateData     Add parameter description

+  @param PrivateData     Points to PeiCore's private instance data.

   @param SecCoreData     Points to a data structure containing information about the PEI core's operating

                          environment, such as the size and location of temporary RAM, the stack location and

                          the BFV location.

@@ -76,9 +75,13 @@ InitializeMemoryServices (
 

 /**

 

-  Install the permanent memory is now available.

-  Creates HOB (PHIT and Stack).

+  This function registers the found memory configuration with the PEI Foundation.

 

+  The usage model is that the PEIM that discovers the permanent memory shall invoke this service.

+  This routine will hold discoveried memory information into PeiCore's private data,

+  and set SwitchStackSignal flag. After PEIM who discovery memory is dispatched,

+  PeiDispatcher will migrate temporary memory to permenement memory.

+  

   @param PeiServices        An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

   @param MemoryBegin        Start of memory address.

   @param MemoryLength       Length of memory.

@@ -120,7 +123,6 @@ PeiInstallPeiMemory (
   @param Memory          Pointer of memory allocated.

 

   @retval EFI_SUCCESS              The allocation was successful

-  @retval EFI_INVALID_PARAMETER    Only AllocateAnyAddress is supported.

   @retval EFI_NOT_AVAILABLE_YET    Called with permanent memory not available

   @retval EFI_OUT_OF_RESOURCES     There is not enough HOB heap to satisfy the requirement

                                    to allocate the number of pages.

@@ -129,15 +131,14 @@ PeiInstallPeiMemory (
 EFI_STATUS

 EFIAPI

 PeiAllocatePages (

-  IN CONST EFI_PEI_SERVICES           **PeiServices,

-  IN EFI_MEMORY_TYPE            MemoryType,

-  IN UINTN                      Pages,

-  OUT EFI_PHYSICAL_ADDRESS      *Memory

+  IN CONST EFI_PEI_SERVICES     **PeiServices,

+  IN       EFI_MEMORY_TYPE      MemoryType,

+  IN       UINTN                Pages,

+  OUT      EFI_PHYSICAL_ADDRESS *Memory

   )

 {

   PEI_CORE_INSTANCE                       *PrivateData;

   EFI_PEI_HOB_POINTERS                    Hob;

-  EFI_PHYSICAL_ADDRESS                    Offset;

   EFI_PHYSICAL_ADDRESS                    *FreeMemoryTop;

   EFI_PHYSICAL_ADDRESS                    *FreeMemoryBottom;

 

@@ -150,7 +151,7 @@ PeiAllocatePages (
   if (!PrivateData->PeiMemoryInstalled) {

     //

     // When PeiInstallMemory is called but CAR has *not* been moved to temporary memory,

-    // the AllocatePage will dependent the field of PEI_CORE_INSTANCE structure.

+    // the AllocatePage will dependent on the field of PEI_CORE_INSTANCE structure.

     //

     if (!PrivateData->SwitchStackSignal) {

       return EFI_NOT_AVAILABLE_YET;

@@ -164,16 +165,9 @@ PeiAllocatePages (
   }

 

   //

-  // Check to see if on 4k boundary

+  // Check to see if on 4k boundary, If not aligned, make the allocation aligned.

   //

-  Offset = *(FreeMemoryTop) & 0xFFF;

-  

-  //

-  // If not aligned, make the allocation aligned.

-  //

-  if (Offset != 0) {

-    *(FreeMemoryTop) -= Offset;

-  }

+  *(FreeMemoryTop) -= *(FreeMemoryTop) & 0xFFF;

   

   //

   // Verify that there is sufficient memory to satisfy the allocation

@@ -210,12 +204,14 @@ PeiAllocatePages (
 

 /**

 

-  Memory allocation service on the CAR.

-

+  Pool allocation service. Before permenent memory is discoveried, the pool will 

+  be allocated the heap in the CAR. Genenrally, the size of heap in temporary 

+  memory does not exceed to 64K, so the biggest pool size could be allocated is 

+  64K.

 

-  @param PeiServices     An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

-  @param Size            Amount of memory required

-  @param Buffer          Address of pointer to the buffer

+  @param PeiServices               An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

+  @param Size                      Amount of memory required

+  @param Buffer                    Address of pointer to the buffer

 

   @retval EFI_SUCCESS              The allocation was successful

   @retval EFI_OUT_OF_RESOURCES     There is not enough heap to satisfy the requirement

@@ -225,26 +221,30 @@ PeiAllocatePages (
 EFI_STATUS

 EFIAPI

 PeiAllocatePool (

-  IN CONST EFI_PEI_SERVICES           **PeiServices,

-  IN UINTN                      Size,

-  OUT VOID                      **Buffer

+  IN CONST EFI_PEI_SERVICES     **PeiServices,

+  IN       UINTN                Size,

+  OUT      VOID                 **Buffer

   )

 {

   EFI_STATUS               Status;

   EFI_HOB_MEMORY_POOL      *Hob;

 

- //

- // If some "post-memory" PEIM wishes to allocate larger pool,

- // it should use AllocatePages service instead.

- //

- ASSERT (Size < 0x10000 - sizeof (EFI_HOB_MEMORY_POOL));

- Status = PeiServicesCreateHob (

+  //

+  // If some "post-memory" PEIM wishes to allocate larger pool,

+  // it should use AllocatePages service instead.

+  //

+  

+  //

+  // Generally, the size of heap in temporary memory does not exceed to 64K,

+  // so the maxmium size of pool is 0x10000 - sizeof (EFI_HOB_MEMORY_POOL)

+  //

+  ASSERT (Size < 0x10000 - sizeof (EFI_HOB_MEMORY_POOL));

+  Status = PeiServicesCreateHob (

              EFI_HOB_TYPE_MEMORY_POOL,

              (UINT16)(sizeof (EFI_HOB_MEMORY_POOL) + Size),

              (VOID **)&Hob

              );

   *Buffer = Hob+1;  

 

-

   return Status;

 }

diff --git a/MdeModulePkg/Core/Pei/PeiMain/PeiMain.c b/MdeModulePkg/Core/Pei/PeiMain/PeiMain.c
index d257eaee43..6e032783d0 100644
--- a/MdeModulePkg/Core/Pei/PeiMain/PeiMain.c
+++ b/MdeModulePkg/Core/Pei/PeiMain/PeiMain.c
@@ -21,8 +21,7 @@ STATIC EFI_PEI_PPI_DESCRIPTOR mMemoryDiscoveredPpi = {
 };

 

 ///

-/// Pei Core Module Variables

-///

+/// Pei service instance

 ///

 STATIC EFI_PEI_SERVICES  gPs = {

   {

@@ -67,11 +66,10 @@ STATIC EFI_PEI_SERVICES  gPs = {
 

 /**

 

-  The entry routine to Pei Core, invoked by PeiMain during transition

+  This routine is invoked by main entry of PeiMain module during transition

   from SEC to PEI. After switching stack in the PEI core, it will restart

   with the old core data.

 

-

   @param SecCoreData     Points to a data structure containing information about the PEI core's operating

                          environment, such as the size and location of temporary RAM, the stack location and

                          the BFV location.

@@ -83,6 +81,7 @@ STATIC EFI_PEI_SERVICES  gPs = {
                          calls and/or code in these early PPIs

   @param Data            Pointer to old core data that is used to initialize the

                          core's data areas.

+                         If NULL, it is first PeiCore entering.

 

   @retval EFI_NOT_FOUND  Never reach

 

@@ -98,13 +97,13 @@ PeiCore (
   PEI_CORE_INSTANCE                                     PrivateData;

   EFI_STATUS                                            Status;

   PEI_CORE_TEMP_POINTERS                                TempPtr;

-  UINT64                                                mTick;

+  UINT64                                                Tick;

   PEI_CORE_INSTANCE                                     *OldCoreData;

   EFI_PEI_CPU_IO_PPI                                    *CpuIo;

   EFI_PEI_PCI_CFG2_PPI                                  *PciCfg;

   PEICORE_FUNCTION_POINTER                              ShadowedPeiCore;

 

-  mTick = 0;

+  Tick = 0;

   OldCoreData = (PEI_CORE_INSTANCE *) Data;

 

   //

@@ -113,16 +112,17 @@ PeiCore (
   // 

   if (PerformanceMeasurementEnabled()) {

     if (OldCoreData == NULL) {

-      mTick = GetPerformanceCounter ();

+      Tick = GetPerformanceCounter ();

     }

   }

 

-  //

-  // PeiCore has been shadowed to memory for first entering, so

-  // just jump to PeiCore in memory here.

-  //

   if (OldCoreData != NULL) {

     ShadowedPeiCore = (PEICORE_FUNCTION_POINTER) (UINTN) OldCoreData->ShadowedPeiCore;

+    

+    //

+    // PeiCore has been shadowed to memory for first entering, so

+    // just jump to PeiCore in memory here.

+    //

     if (ShadowedPeiCore != NULL) {

       OldCoreData->ShadowedPeiCore = NULL;

       ShadowedPeiCore (

@@ -142,6 +142,10 @@ PeiCore (
     PrivateData.ServiceTableShadow.CpuIo  = CpuIo;

     PrivateData.ServiceTableShadow.PciCfg = PciCfg;

   } else {

+    //

+    // If OldCoreData is NULL, means current is first Peicore's entering.

+    //

+    

     ZeroMem (&PrivateData, sizeof (PEI_CORE_INSTANCE));

     PrivateData.Signature = PEI_CORE_HANDLE_SIGNATURE;

     CopyMem (&PrivateData.ServiceTableShadow, &gPs, sizeof (gPs));

@@ -186,11 +190,11 @@ PeiCore (
       FixedPcdGet32 (PcdStatusCodeValuePeiCoreEntry)

       );

 

-    PERF_START (NULL,"PEI", NULL, mTick);

+    PERF_START (NULL,"PEI", NULL, Tick);

     //

     // If first pass, start performance measurement.

     //

-    PERF_START (NULL,"PreMem", NULL, mTick);

+    PERF_START (NULL,"PreMem", NULL, Tick);

 

     //

     // If SEC provided any PPI services to PEI, install them.

diff --git a/MdeModulePkg/Core/Pei/Security/Security.c b/MdeModulePkg/Core/Pei/Security/Security.c
index 7460707a27..469686ff23 100644
--- a/MdeModulePkg/Core/Pei/Security/Security.c
+++ b/MdeModulePkg/Core/Pei/Security/Security.c
@@ -62,7 +62,8 @@ InitializeSecurityServices (
 /**

 

   Provide a callback for when the security PPI is installed.

-

+  This routine will cache installed security PPI into PeiCore's private data.

+  

   @param PeiServices        An indirect pointer to the EFI_PEI_SERVICES table published by the PEI Foundation.

   @param NotifyDescriptor   The descriptor for the notification event.

   @param Ppi                Pointer to the PPI in question.

@@ -105,7 +106,7 @@ SecurityPpiNotifyCallback (
 

   @retval EFI_SUCCESS              Image is OK

   @retval EFI_SECURITY_VIOLATION   Image is illegal

-

+  @retval EFI_NOT_FOUND            If security PPI is not installed.

 **/

 EFI_STATUS

 VerifyPeim (

@@ -148,10 +149,9 @@ VerifyPeim (
 /**

   Verify a Firmware volume.

 

-  @param CurrentFvAddress - Pointer to the current Firmware Volume under consideration

+  @param CurrentFvAddress   Pointer to the current Firmware Volume under consideration

 

-  @retval EFI_SUCCESS              Firmware Volume is legal

-  @retval EFI_SECURITY_VIOLATION   Firmware Volume fails integrity test

+  @retval EFI_SUCCESS       Firmware Volume is legal

 

 **/

 EFI_STATUS