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
  32 typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI   EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI;
  33
  34
  35 /**
  36   Processes the input section and returns the data contained therein
  37   along with the authentication status.
  38
  39   The ExtractSection() function processes the input section and
  40   returns a pointer to the section contents. If the section being
  41   extracted does not require processing (if the section
  42   GuidedSectionHeader.Attributes has the
  43   EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then
  44   OutputBuffer is just updated to point to the start of the
  45   section's contents. Otherwise, *Buffer must be allocated
  46   from PEI permanent memory.
  47
  48   @param This                   Indicates the EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI
  49                                 instance.
  50   @param InputSection           Buffer containing the input GUIDed section to be
  51                                 processed.
  52   @param OutputBuffer           *OutputBuffer is allocated from PEI permanent memory
  53                                 and contains the new section stream.
  54   @param OutputSize             A pointer to a caller-allocated UINTN in which
  55                                 the size of *OutputBuffer allocation is stored.
  56                                 If the function returns anything other than
  57                                 EFI_SUCCESS, the value of *OutputSize is undefined.
  58   @param AuthenticationStatus   A pointer to a caller-allocated UINT32 that indicates
  59                                 the authentication status of the output buffer.
  60                                 If the input section's
  61                                 GuidedSectionHeader.Attributes field has the
  62                                 EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear,
  63                                 *AuthenticationStatus must return zero. These bits
  64                                 reflect the status of the extraction operation.
  65                                 If the function returns anything other than EFI_SUCCESS,
  66                                 the value of *AuthenticationStatus is undefined.
  67
  68   @retval EFI_SUCCESS           The InputSection was successfully processed and the
  69                                 section contents were returned.
  70   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the request.
  71   @retval EFI_INVALID_PARAMETER The GUID in InputSection does not match this instance of the
  72                                 GUIDed Section Extraction PPI.
  73 **/
  74 typedef
  75 EFI_STATUS
  76 (EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)(
  77   IN  CONST  EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This,
  78   IN  CONST  VOID                                  *InputSection,
  79   OUT VOID                                         **OutputBuffer,
  80   OUT UINTN                                        *OutputSize,
  81   OUT UINT32                                       *AuthenticationStatus
  82 );
  83
  84 ///
  85 /// If a GUID-defined section is encountered when doing section extraction,
  86 /// the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance
  87 /// calls the appropriate instance of the GUIDed Section
  88 /// Extraction PPI to extract the section stream contained
  89 /// therein.
  90 ///
  91 struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {
  92   EFI_PEI_EXTRACT_GUIDED_SECTION ExtractSection;
  93 };
  94
  95
  96
  97 #endif
  98