MdePkg/Include/Ppi/GuidedSectionExtraction.h

   1 /** @file
   2   If a GUID-defined section is encountered when doing section extraction,
   3   the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance
   4   calls the appropriate instance of the GUIDed Section Extraction PPI
   5   to extract the section stream contained therein.
   6
   7   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8   SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10   @par Revision Reference:
  11   This PPI is introduced in PI Version 1.0.
  12
  13 **/
  14
  15 #ifndef __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__
  16 #define __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__
  17
  18 //
  19 // Typically, protocol interface structures are identified
  20 // by associating them with a GUID. Each instance of
  21 // a protocol with a given GUID must have
  22 // the same interface structure. While all instances of
  23 // the GUIDed Section Extraction PPI must have
  24 // the same interface structure, they do not all have
  25 // te same GUID. The GUID that is associated with
  26 // an instance of the GUIDed Section Extraction Protocol
  27 // is used to correlate it with the GUIDed section type
  28 // that it is intended to process.
  29 //
  30
  31 typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI;
  32
  33 /**
  34   Processes the input section and returns the data contained therein
  35   along with the authentication status.
  36
  37   The ExtractSection() function processes the input section and
  38   returns a pointer to the section contents. If the section being
  39   extracted does not require processing (if the section
  40   GuidedSectionHeader.Attributes has the
  41   EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then
  42   OutputBuffer is just updated to point to the start of the
  43   section's contents. Otherwise, *Buffer must be allocated
  44   from PEI permanent memory.
  45
  46   @param This                   Indicates the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI
  47                                 instance.
  48   @param InputSection           Buffer containing the input GUIDed section to be
  49                                 processed.
  50   @param OutputBuffer           *OutputBuffer is allocated from PEI permanent memory
  51                                 and contains the new section stream.
  52   @param OutputSize             A pointer to a caller-allocated UINTN in which
  53                                 the size of *OutputBuffer allocation is stored.
  54                                 If the function returns anything other than
  55                                 EFI_SUCCESS, the value of *OutputSize is undefined.
  56   @param AuthenticationStatus   A pointer to a caller-allocated UINT32 that indicates
  57                                 the authentication status of the output buffer.
  58                                 If the input section's
  59                                 GuidedSectionHeader.Attributes field has the
  60                                 EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear,
  61                                 *AuthenticationStatus must return zero. These bits
  62                                 reflect the status of the extraction operation.
  63                                 If the function returns anything other than EFI_SUCCESS,
  64                                 the value of *AuthenticationStatus is undefined.
  65
  66   @retval EFI_SUCCESS           The InputSection was successfully processed and the
  67                                 section contents were returned.
  68   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the request.
  69   @retval EFI_INVALID_PARAMETER The GUID in InputSection does not match this instance of the
  70                                 GUIDed Section Extraction PPI.
  71 **/
  72 typedef
  73 EFI_STATUS
  74 (EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)(
  75   IN  CONST  EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This,
  76   IN  CONST  VOID                                  *InputSection,
  77   OUT VOID                                         **OutputBuffer,
  78   OUT UINTN                                        *OutputSize,
  79   OUT UINT32                                       *AuthenticationStatus
  80   );
  81
  82 ///
  83 /// If a GUID-defined section is encountered when doing section extraction,
  84 /// the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance
  85 /// calls the appropriate instance of the GUIDed Section
  86 /// Extraction PPI to extract the section stream contained
  87 /// therein.
  88 ///
  89 struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {
  90   EFI_PEI_EXTRACT_GUIDED_SECTION    ExtractSection;
  91 };
  92
  93 #endif