]> git.proxmox.com Git - mirror_edk2.git/blobdiff - MdeModulePkg/Core/DxeIplPeim/DxeLoad.c
Add doxygen style comments for functions in DxeIpl.
[mirror_edk2.git] / MdeModulePkg / Core / DxeIplPeim / DxeLoad.c
index 0e0f448cb0716f7b191a2471dd59e091de216472..db9e1dee91b220f098ee962beee7ab675e7d1142 100644 (file)
@@ -16,21 +16,97 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include "DxeIpl.h"\r
 #include <Ppi/GuidedSectionExtraction.h>\r
 \r
+\r
+\r
+/**\r
+  The ExtractSection() function processes the input section and\r
+  returns a pointer to the section contents. If the section being\r
+  extracted does not require processing (if the section\r
+  GuidedSectionHeader.Attributes has the\r
+  EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then\r
+  OutputBuffer is just updated to point to the start of the\r
+  section's contents. Otherwise, *Buffer must be allocated\r
+  from PEI permanent memory.\r
+\r
+  @param This                   Indicates the\r
+                                EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI instance.\r
+                                Buffer containing the input GUIDed section to be\r
+                                processed. OutputBuffer OutputBuffer is\r
+                                allocated from PEI permanent memory and contains\r
+                                the new section stream.\r
+  @param CompressionSection     A pointer to the input buffer, which contains\r
+                                the input section to be processed.\r
+  @param OutputBuffer           A pointer to a caller-allocated buffer, whose\r
+                                size is specified by the contents of OutputSize.\r
+  @param OutputSize             A pointer to a caller-allocated\r
+                                UINTN in which the size of *OutputBuffer\r
+                                allocation is stored. If the function\r
+                                returns anything other than EFI_SUCCESS,\r
+                                the value of OutputSize is undefined.\r
+  @param AuthenticationStatus   A pointer to a caller-allocated\r
+                                UINT32 that indicates the\r
+                                authentication status of the\r
+                                output buffer. If the input\r
+                                section's GuidedSectionHeader.\r
+                                Attributes field has the\r
+                                EFI_GUIDED_SECTION_AUTH_STATUS_VALID \r
+                                bit as clear,\r
+                                AuthenticationStatus must return\r
+                                zero. These bits reflect the\r
+                                status of the extraction\r
+                                operation. If the function\r
+                                returns anything other than\r
+                                EFI_SUCCESS, the value of\r
+                                AuthenticationStatus is\r
+                                undefined.\r
+  \r
+  @retval EFI_SUCCESS           The InputSection was\r
+                                successfully processed and the\r
+                                section contents were returned.\r
+  \r
+  @retval EFI_OUT_OF_RESOURCES  The system has insufficient\r
+                                resources to process the request.\r
+  \r
+  @reteval EFI_INVALID_PARAMETER The GUID in InputSection does\r
+                                not match this instance of the\r
+                                GUIDed Section Extraction PPI.\r
+\r
+**/\r
 EFI_STATUS\r
 CustomGuidedSectionExtract (\r
   IN CONST  EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This,\r
-  IN CONST  VOID                                  *InputSection,\r
+  IN CONST  VOID                                  *CompressionSection,\r
   OUT       VOID                                  **OutputBuffer,\r
   OUT       UINTN                                 *OutputSize,\r
   OUT       UINT32                                *AuthenticationStatus\r
 );\r
 \r
-STATIC\r
+\r
+/**\r
+   Decompresses a section to the output buffer.\r
+\r
+   This function lookes up the compression type field in the input section and\r
+   applies the appropriate compression algorithm to compress the section to a\r
+   callee allocated buffer.\r
+    \r
+   @param  This                  Points to this instance of the\r
+                                 EFI_PEI_DECOMPRESS_PEI PPI.\r
+   @param  CompressionSection    Points to the compressed section.\r
+   @param  OutputBuffer          Holds the returned pointer to the decompressed\r
+                                 sections.\r
+   @param  OutputSize            Holds the returned size of the decompress\r
+                                 section streams.\r
+   \r
+   @retval EFI_SUCCESS           The section was decompressed successfully.\r
+                                 OutputBuffer contains the resulting data and\r
+                                 OutputSize contains the resulting size.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI \r
 Decompress (\r
   IN CONST  EFI_PEI_DECOMPRESS_PPI  *This,\r
-  IN CONST  EFI_COMPRESSION_SECTION *InputSection,\r
+  IN CONST  EFI_COMPRESSION_SECTION *CompressionSection,\r
   OUT       VOID                    **OutputBuffer,\r
   OUT       UINTN                   *OutputSize\r
 );\r
@@ -79,8 +155,9 @@ static EFI_PEI_PPI_DESCRIPTOR     mPpiSignal = {
   @param  FfsHandle   The handle of FFS file.\r
   @param  PeiServices General purpose services available to\r
                       every PEIM.\r
-  @return EFI_SUCESS \r
-*/ \r
+  @return EFI_SUCESS\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 PeimInitializeDxeIpl (\r
@@ -117,16 +194,16 @@ PeimInitializeDxeIpl (
       // Install custom extraction guid ppi\r
       //\r
       if (ExtractHandlerNumber > 0) {\r
-       GuidPpi = NULL;\r
-       GuidPpi = (EFI_PEI_PPI_DESCRIPTOR *) AllocatePool (ExtractHandlerNumber * sizeof (EFI_PEI_PPI_DESCRIPTOR));\r
-       ASSERT (GuidPpi != NULL);\r
-       while (ExtractHandlerNumber-- > 0) {\r
-         GuidPpi->Flags = EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST;\r
-         GuidPpi->Ppi   = &mCustomGuidedSectionExtractionPpi;\r
-         GuidPpi->Guid  = &(ExtractHandlerGuidTable [ExtractHandlerNumber]);\r
-         Status = PeiServicesInstallPpi (GuidPpi++);\r
-         ASSERT_EFI_ERROR(Status);\r
-       }\r
+        GuidPpi = NULL;\r
+        GuidPpi = (EFI_PEI_PPI_DESCRIPTOR *) AllocatePool (ExtractHandlerNumber * sizeof (EFI_PEI_PPI_DESCRIPTOR));\r
+        ASSERT (GuidPpi != NULL);\r
+        while (ExtractHandlerNumber-- > 0) {\r
+          GuidPpi->Flags = EFI_PEI_PPI_DESCRIPTOR_PPI | EFI_PEI_PPI_DESCRIPTOR_TERMINATE_LIST;\r
+          GuidPpi->Ppi   = &mCustomGuidedSectionExtractionPpi;\r
+          GuidPpi->Guid  = &(ExtractHandlerGuidTable [ExtractHandlerNumber]);\r
+          Status = PeiServicesInstallPpi (GuidPpi++);\r
+          ASSERT_EFI_ERROR(Status);\r
+        }\r
       }\r
     } else {\r
       ASSERT (FALSE);\r
@@ -151,6 +228,7 @@ PeimInitializeDxeIpl (
    \r
    @return EFI_SUCCESS              DXE core was successfully loaded. \r
    @return EFI_OUT_OF_RESOURCES     There are not enough resources to load DXE core.\r
+\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -183,7 +261,7 @@ DxeLoadCore (
   } else if (BootMode == BOOT_IN_RECOVERY_MODE) {\r
     Status = PeiRecoverFirmware ();\r
     if (EFI_ERROR (Status)) {\r
-      DEBUG ((EFI_D_ERROR, "Load Recovery Capsule Failed.(Status = %r)\n", Status));\r
+      DEBUG ((DEBUG_ERROR, "Load Recovery Capsule Failed.(Status = %r)\n", Status));\r
       CpuDeadLoop ();\r
     }\r
 \r
@@ -266,12 +344,12 @@ DxeLoadCore (
     PtrPeImage.Pe32 = (EFI_IMAGE_NT_HEADERS32 *) ((UINTN) DxeCoreAddress + ((EFI_IMAGE_DOS_HEADER *) (UINTN) DxeCoreAddress)->e_lfanew);\r
     \r
     if (PtrPeImage.Pe32->FileHeader.Machine != IMAGE_FILE_MACHINE_IA64) {\r
-      DEBUG ((EFI_D_INFO | EFI_D_LOAD, "Loading DXE CORE at 0x%10p EntryPoint=0x%10p\n", (VOID *)(UINTN)DxeCoreAddress, (VOID *)(UINTN)DxeCoreEntryPoint));\r
+      DEBUG ((DEBUG_INFO | DEBUG_LOAD, "Loading DXE CORE at 0x%10p EntryPoint=0x%10p\n", (VOID *)(UINTN)DxeCoreAddress, (VOID *)(UINTN)DxeCoreEntryPoint));\r
     } else {\r
       //\r
       // For IPF Image, the real entry point should be print.\r
       //\r
-      DEBUG ((EFI_D_INFO | EFI_D_LOAD, "Loading DXE CORE at 0x%10p EntryPoint=0x%10p\n", (VOID *)(UINTN)DxeCoreAddress, (VOID *)(UINTN)(*(UINT64 *)(UINTN)DxeCoreEntryPoint)));\r
+      DEBUG ((DEBUG_INFO | DEBUG_LOAD, "Loading DXE CORE at 0x%10p EntryPoint=0x%10p\n", (VOID *)(UINTN)DxeCoreAddress, (VOID *)(UINTN)(*(UINT64 *)(UINTN)DxeCoreEntryPoint)));\r
     }\r
 \r
   DEBUG_CODE_END ();\r
@@ -290,6 +368,9 @@ DxeLoadCore (
   return EFI_OUT_OF_RESOURCES;\r
 }\r
 \r
+\r
+\r
+\r
 /**\r
    Find DxeCore driver from all First Volumes.\r
 \r
@@ -297,7 +378,8 @@ DxeLoadCore (
    \r
    @return EFI_SUCESS   Success to find the FFS in specificed FV\r
    @return others       Fail to find the FFS in specificed FV\r
- */\r
+\r
+**/\r
 EFI_STATUS\r
 DxeIplFindDxeCore (\r
   OUT EFI_PEI_FILE_HANDLE   *FileHandle\r
@@ -324,6 +406,9 @@ DxeIplFindDxeCore (
   return EFI_NOT_FOUND;\r
 }\r
 \r
+\r
+\r
+\r
 /**\r
    Loads and relocates a PE/COFF image into memory.\r
 \r
@@ -334,6 +419,7 @@ DxeIplFindDxeCore (
    \r
    @return EFI_SUCCESS           The file was loaded and relocated\r
    @return EFI_OUT_OF_RESOURCES  There was not enough memory to load and relocate the PE/COFF file\r
+\r
 **/\r
 EFI_STATUS\r
 PeiLoadFile (\r
@@ -406,6 +492,9 @@ PeiLoadFile (
   return EFI_SUCCESS;\r
 }\r
 \r
+\r
+\r
+\r
 /**\r
   The ExtractSection() function processes the input section and\r
   returns a pointer to the section contents. If the section being\r
@@ -422,13 +511,15 @@ PeiLoadFile (
                                 processed. OutputBuffer OutputBuffer is\r
                                 allocated from PEI permanent memory and contains\r
                                 the new section stream.\r
-  \r
+  @param InputSection           A pointer to the input buffer, which contains\r
+                                the input section to be processed.\r
+  @param OutputBuffer           A pointer to a caller-allocated buffer, whose\r
+                                size is specified by the contents of OutputSize.\r
   @param OutputSize             A pointer to a caller-allocated\r
                                 UINTN in which the size of *OutputBuffer\r
                                 allocation is stored. If the function\r
                                 returns anything other than EFI_SUCCESS,\r
                                 the value of OutputSize is undefined.\r
-  \r
   @param AuthenticationStatus   A pointer to a caller-allocated\r
                                 UINT32 that indicates the\r
                                 authentication status of the\r
@@ -456,6 +547,7 @@ PeiLoadFile (
   @reteval EFI_INVALID_PARAMETER The GUID in InputSection does\r
                                 not match this instance of the\r
                                 GUIDed Section Extraction PPI.\r
+\r
 **/\r
 EFI_STATUS\r
 CustomGuidedSectionExtract (\r
@@ -488,7 +580,7 @@ CustomGuidedSectionExtract (
            );\r
   \r
   if (EFI_ERROR (Status)) {\r
-    DEBUG ((EFI_D_ERROR, "GetInfo from guided section Failed - %r\n", Status));\r
+    DEBUG ((DEBUG_ERROR, "GetInfo from guided section Failed - %r\n", Status));\r
     return Status;\r
   }\r
   \r
@@ -510,7 +602,7 @@ CustomGuidedSectionExtract (
     if (*OutputBuffer == NULL) {\r
       return EFI_OUT_OF_RESOURCES;\r
     }\r
-    DEBUG ((EFI_D_INFO, "Customed Guided section Memory Size required is 0x%x and address is 0x%p\n", OutputBufferSize, *OutputBuffer));\r
+    DEBUG ((DEBUG_INFO, "Customed Guided section Memory Size required is 0x%x and address is 0x%p\n", OutputBufferSize, *OutputBuffer));\r
     //\r
     // *OutputBuffer still is one section. Adjust *OutputBuffer offset, \r
     // skip EFI section header to make section data at page alignment.\r
@@ -529,7 +621,7 @@ CustomGuidedSectionExtract (
     //\r
     // Decode failed\r
     //\r
-    DEBUG ((EFI_D_ERROR, "Extract guided section Failed - %r\n", Status));\r
+    DEBUG ((DEBUG_ERROR, "Extract guided section Failed - %r\n", Status));\r
     return Status;\r
   }\r
   \r
@@ -538,7 +630,28 @@ CustomGuidedSectionExtract (
   return EFI_SUCCESS;\r
 }\r
 \r
-STATIC\r
+\r
+\r
+/**\r
+   Decompresses a section to the output buffer.\r
+\r
+   This function lookes up the compression type field in the input section and\r
+   applies the appropriate compression algorithm to compress the section to a\r
+   callee allocated buffer.\r
+    \r
+   @param  This                  Points to this instance of the\r
+                                 EFI_PEI_DECOMPRESS_PEI PPI.\r
+   @param  CompressionSection    Points to the compressed section.\r
+   @param  OutputBuffer          Holds the returned pointer to the decompressed\r
+                                 sections.\r
+   @param  OutputSize            Holds the returned size of the decompress\r
+                                 section streams.\r
+   \r
+   @retval EFI_SUCCESS           The section was decompressed successfully.\r
+                                 OutputBuffer contains the resulting data and\r
+                                 OutputSize contains the resulting size.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI \r
 Decompress (\r
@@ -583,7 +696,7 @@ Decompress (
       //\r
       // GetInfo failed\r
       //\r
-      DEBUG ((EFI_D_ERROR, "Decompress GetInfo Failed - %r\n", Status));\r
+      DEBUG ((DEBUG_ERROR, "Decompress GetInfo Failed - %r\n", Status));\r
       return EFI_NOT_FOUND;\r
     }\r
     //\r
@@ -617,7 +730,7 @@ Decompress (
       //\r
       // Decompress failed\r
       //\r
-      DEBUG ((EFI_D_ERROR, "Decompress Failed - %r\n", Status));\r
+      DEBUG ((DEBUG_ERROR, "Decompress Failed - %r\n", Status));\r
       return EFI_NOT_FOUND;\r
     }\r
     break;\r
@@ -656,6 +769,19 @@ Decompress (
   return EFI_SUCCESS;\r
 }\r
 \r
+\r
+\r
+\r
+/**\r
+   Updates the Stack HOB passed to DXE phase.\r
+\r
+   This function traverses the whole HOB list and update the stack HOB to\r
+   reflect the real stack that is used by DXE core.\r
+\r
+   @param BaseAddress           The lower address of stack used by DxeCore.\r
+   @param Length                The length of stack used by DxeCore.\r
+\r
+**/\r
 VOID\r
 UpdateStackHob (\r
   IN EFI_PHYSICAL_ADDRESS        BaseAddress,\r