Refine the comments for the function header.

[mirror_edk2.git] / MdeModulePkg / Universal / SectionExtractionPei / SectionExtractionPei.c

diff --git a/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c b/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c
index 55c9224faeaf32c19ab6d6ea8d3b8dfd14cbdbdc..c4a3508fbd2b91998a78205034a83744de350577 100644 (file)
--- a/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c
+++ b/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c
@@ -19,9 +19,60 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Library/MemoryAllocationLib.h>\r
 #include <Library/PeiServicesLib.h>\r
 \r
-//\r
-// Function prototype for Section Extraction PPI service\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 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
+  @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
+  @retval 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
 EFIAPI\r
 CustomGuidedSectionExtract (\r