Refine the comments for the function header.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Eric Dong <eric.dong@intel.com>
Reviewed-by: Feng Tian <feng.tian@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@15827 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c b/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c
index 0cdfdefeb8a948884e311ead23b55be42d43a25e..b100883be69ab2259134dc047143bb37a560766a 100644 (file)
--- a/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c
+++ b/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c
@@ -20,9 +20,89 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 #include <Library/BaseMemoryLib.h>\r
 #include <Library/UefiBootServicesTableLib.h>\r
 \r
-//\r
-// Function prototype for Section Extraction Protocol service\r
-//\r
+/**\r
+  The ExtractSection() function processes the input section and\r
+  allocates a buffer from the pool in which it returns the section\r
+  contents. If the section being extracted contains\r
+  authentication information (the section's\r
+  GuidedSectionHeader.Attributes field has the\r
+  EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values\r
+  returned in AuthenticationStatus must reflect the results of\r
+  the authentication operation. Depending on the algorithm and\r
+  size of the encapsulated data, the time that is required to do\r
+  a full authentication may be prohibitively long for some\r
+  classes of systems. To indicate this, use\r
+  EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by\r
+  the security policy driver (see the Platform Initialization\r
+  Driver Execution Environment Core Interface Specification for\r
+  more details and the GUID definition). If the\r
+  EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle\r
+  database, then, if possible, full authentication should be\r
+  skipped and the section contents simply returned in the\r
+  OutputBuffer. In this case, the\r
+  EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus\r
+  must be set on return. ExtractSection() is callable only from\r
+  TPL_NOTIFY and below. Behavior of ExtractSection() at any\r
+  EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is\r
+  defined in RaiseTPL() in the UEFI 2.0 specification.\r
+\r
+\r
+  @param This         Indicates the\r
+                      EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.\r
+  @param InputSection Buffer containing the input GUIDed section\r
+                      to be processed. OutputBuffer OutputBuffer\r
+                      is allocated from boot services pool\r
+                      memory and contains the new section\r
+                      stream. The caller is responsible for\r
+                      freeing this buffer.\r
+  @param OutputBuffer *OutputBuffer is allocated from boot services\r
+                      pool memory and contains the new section stream.\r
+                      The caller is responsible for freeing this buffer.\r
+  @param OutputSize   A pointer to a caller-allocated UINTN in\r
+                      which the size of OutputBuffer allocation\r
+                      is stored. If the function returns\r
+                      anything other than EFI_SUCCESS, the value\r
+                      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
+                              output buffer. If the input\r
+                              section's\r
+                              GuidedSectionHeader.Attributes\r
+                              field has the\r
+                              EFI_GUIDED_SECTION_AUTH_STATUS_VAL\r
+                              bit as clear, AuthenticationStatus\r
+                              must return zero. Both local bits\r
+                              (19:16) and aggregate bits (3:0)\r
+                              in AuthenticationStatus are\r
+                              returned by ExtractSection().\r
+                              These bits reflect the status of\r
+                              the extraction operation. The bit\r
+                              pattern in both regions must be\r
+                              the same, as the local and\r
+                              aggregate authentication statuses\r
+                              have equivalent meaning at this\r
+                              level. If the function returns\r
+                              anything other than EFI_SUCCESS,\r
+                              the value of AuthenticationStatus\r
+                              is undefined.\r
+\r
+\r
+  @retval EFI_SUCCESS          The InputSection was successfully\r
+                               processed and the section contents were\r
+                               returned.\r
+\r
+  @retval EFI_OUT_OF_RESOURCES The system has insufficient\r
+                               resources to process the\r
+                               request.\r
+\r
+  @retval EFI_INVALID_PARAMETER The GUID in InputSection does\r
+                                not match this instance of the\r
+                                GUIDed Section Extraction\r
+                                Protocol.\r
+\r
+**/\r
 EFI_STATUS\r
 EFIAPI\r
 CustomGuidedSectionExtract (\r

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