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

2 files changed, 137 insertions, 6 deletions

diff --git a/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c b/MdeModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.c
index 0cdfdefeb8..b100883be6 100644
--- 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>

 #include <Library/UefiBootServicesTableLib.h>

 

-//

-// Function prototype for Section Extraction Protocol service

-//

+/**

+  The ExtractSection() function processes the input section and

+  allocates a buffer from the pool in which it returns the section

+  contents. If the section being extracted contains

+  authentication information (the section's

+  GuidedSectionHeader.Attributes field has the

+  EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values

+  returned in AuthenticationStatus must reflect the results of

+  the authentication operation. Depending on the algorithm and

+  size of the encapsulated data, the time that is required to do

+  a full authentication may be prohibitively long for some

+  classes of systems. To indicate this, use

+  EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by

+  the security policy driver (see the Platform Initialization

+  Driver Execution Environment Core Interface Specification for

+  more details and the GUID definition). If the

+  EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle

+  database, then, if possible, full authentication should be

+  skipped and the section contents simply returned in the

+  OutputBuffer. In this case, the

+  EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus

+  must be set on return. ExtractSection() is callable only from

+  TPL_NOTIFY and below. Behavior of ExtractSection() at any

+  EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is

+  defined in RaiseTPL() in the UEFI 2.0 specification.

+

+

+  @param This         Indicates the

+                      EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.

+  @param InputSection Buffer containing the input GUIDed section

+                      to be processed. OutputBuffer OutputBuffer

+                      is allocated from boot services pool

+                      memory and contains the new section

+                      stream. The caller is responsible for

+                      freeing this buffer.

+  @param OutputBuffer *OutputBuffer is allocated from boot services

+                      pool memory and contains the new section stream.

+                      The caller is responsible for freeing this buffer.

+  @param OutputSize   A pointer to a caller-allocated UINTN in

+                      which the size of OutputBuffer allocation

+                      is stored. If the function returns

+                      anything other than EFI_SUCCESS, the value

+                      of OutputSize is undefined.

+

+  @param AuthenticationStatus A pointer to a caller-allocated

+                              UINT32 that indicates the

+                              authentication status of the

+                              output buffer. If the input

+                              section's

+                              GuidedSectionHeader.Attributes

+                              field has the

+                              EFI_GUIDED_SECTION_AUTH_STATUS_VAL

+                              bit as clear, AuthenticationStatus

+                              must return zero. Both local bits

+                              (19:16) and aggregate bits (3:0)

+                              in AuthenticationStatus are

+                              returned by ExtractSection().

+                              These bits reflect the status of

+                              the extraction operation. The bit

+                              pattern in both regions must be

+                              the same, as the local and

+                              aggregate authentication statuses

+                              have equivalent meaning at this

+                              level. If the function returns

+                              anything other than EFI_SUCCESS,

+                              the value of AuthenticationStatus

+                              is undefined.

+

+

+  @retval EFI_SUCCESS          The InputSection was successfully

+                               processed and the section contents were

+                               returned.

+

+  @retval EFI_OUT_OF_RESOURCES The system has insufficient

+                               resources to process the

+                               request.

+

+  @retval EFI_INVALID_PARAMETER The GUID in InputSection does

+                                not match this instance of the

+                                GUIDed Section Extraction

+                                Protocol.

+

+**/

 EFI_STATUS

 EFIAPI

 CustomGuidedSectionExtract (

diff --git a/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c b/MdeModulePkg/Universal/SectionExtractionPei/SectionExtractionPei.c
index 55c9224fae..c4a3508fbd 100644
--- 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>

 #include <Library/PeiServicesLib.h>

 

-//

-// Function prototype for Section Extraction PPI service

-//

+/**

+  The ExtractSection() function processes the input section and

+  returns a pointer to the section contents. If the section being

+  extracted does not require processing (if the section

+  GuidedSectionHeader.Attributes has the

+  EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then

+  OutputBuffer is just updated to point to the start of the

+  section's contents. Otherwise, *Buffer must be allocated

+  from PEI permanent memory.

+

+  @param This                   Indicates the

+                                EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI instance.

+                                Buffer containing the input GUIDed section to be

+                                processed. OutputBuffer OutputBuffer is

+                                allocated from PEI permanent memory and contains

+                                the new section stream.

+  @param InputSection           A pointer to the input buffer, which contains

+                                the input section to be processed.

+  @param OutputBuffer           A pointer to a caller-allocated buffer, whose

+                                size is specified by the contents of OutputSize.

+  @param OutputSize             A pointer to a caller-allocated

+                                UINTN in which the size of *OutputBuffer

+                                allocation is stored. If the function

+                                returns anything other than EFI_SUCCESS,

+                                the value of OutputSize is undefined.

+  @param AuthenticationStatus   A pointer to a caller-allocated

+                                UINT32 that indicates the

+                                authentication status of the

+                                output buffer. If the input

+                                section's GuidedSectionHeader.

+                                Attributes field has the

+                                EFI_GUIDED_SECTION_AUTH_STATUS_VALID 

+                                bit as clear,

+                                AuthenticationStatus must return

+                                zero. These bits reflect the

+                                status of the extraction

+                                operation. If the function

+                                returns anything other than

+                                EFI_SUCCESS, the value of

+                                AuthenticationStatus is

+                                undefined.

+  

+  @retval EFI_SUCCESS           The InputSection was

+                                successfully processed and the

+                                section contents were returned.

+  

+  @retval EFI_OUT_OF_RESOURCES  The system has insufficient

+                                resources to process the request.

+  

+  @retval EFI_INVALID_PARAMETER The GUID in InputSection does

+                                not match this instance of the

+                                GUIDed Section Extraction PPI.

+

+**/

 EFI_STATUS

 EFIAPI

 CustomGuidedSectionExtract (