MdePkg: Replace BSD License with BSD+Patent License

[mirror_edk2.git] / MdePkg / Include / Ppi / GuidedSectionExtraction.h

/** @file\r
  If a GUID-defined section is encountered when doing section extraction,\r
  the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance\r
  calls the appropriate instance of the GUIDed Section Extraction PPI\r
  to extract the section stream contained therein.\r
\r
  Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
  @par Revision Reference:\r
  This PPI is introduced in PI Version 1.0.\r
\r
**/\r
\r
#ifndef __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__\r
#define __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__\r
\r
//\r
// Typically, protocol interface structures are identified\r
// by associating them with a GUID. Each instance of\r
// a protocol with a given GUID must have\r
// the same interface structure. While all instances of\r
// the GUIDed Section Extraction PPI must have\r
// the same interface structure, they do not all have\r
// te same GUID. The GUID that is associated with\r
// an instance of the GUIDed Section Extraction Protocol\r
// is used to correlate it with the GUIDed section type\r
// that it is intended to process.\r
//\r
\r
\r
typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI   EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI;\r
\r
\r
/**\r
  Processes the input section and returns the data contained therein\r
  along with the authentication status.\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 EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI\r
                                instance.\r
  @param InputSection           Buffer containing the input GUIDed section to be\r
                                processed.\r
  @param OutputBuffer           *OutputBuffer is allocated from PEI permanent memory\r
                                and contains the new section stream.\r
  @param OutputSize             A pointer to a caller-allocated UINTN in which\r
                                the size of *OutputBuffer allocation is stored.\r
                                If the function returns anything other than\r
                                EFI_SUCCESS, the value of *OutputSize is undefined.\r
  @param AuthenticationStatus   A pointer to a caller-allocated UINT32 that indicates\r
                                the authentication status of the output buffer.\r
                                If the input section's\r
                                GuidedSectionHeader.Attributes field has the\r
                                EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear,\r
                                *AuthenticationStatus must return zero. These bits\r
                                reflect the status of the extraction operation.\r
                                If the function returns anything other than EFI_SUCCESS,\r
                                the value of *AuthenticationStatus is undefined.\r
\r
  @retval EFI_SUCCESS           The InputSection was successfully processed and the\r
                                section contents were returned.\r
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the request.\r
  @retval EFI_INVALID_PARAMETER The GUID in InputSection does not match this instance of the\r
                                GUIDed Section Extraction PPI.\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)(\r
  IN  CONST  EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This,\r
  IN  CONST  VOID                                  *InputSection,\r
  OUT VOID                                         **OutputBuffer,\r
  OUT UINTN                                        *OutputSize,\r
  OUT UINT32                                       *AuthenticationStatus\r
);\r
\r
///\r
/// If a GUID-defined section is encountered when doing section extraction,\r
/// the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance\r
/// calls the appropriate instance of the GUIDed Section\r
/// Extraction PPI to extract the section stream contained\r
/// therein.\r
///\r
struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {\r
  EFI_PEI_EXTRACT_GUIDED_SECTION ExtractSection;\r
};\r
\r
\r
\r
#endif\r
\r