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 - 2007, Intel Corporation
   8   All rights reserved. This program and the accompanying materials
   9   are licensed and made available under the terms and conditions of the BSD License
  10   which accompanies this distribution.  The full text of the license may be found at
  11   http://opensource.org/licenses/bsd-license.php
  12
  13   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  14   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  15
  16   @par Revision Reference:
  17   This PPI is defined in PI Version 1.00.
  18
  19 **/
  20
  21 #ifndef __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__
  22 #define __EFI_GUIDED_SECTION_EXTRACTION_PPI_H__
  23
  24 //
  25 // Typically, protocol interface structures are identified
  26 // by associating them with a GUID. Each instance of
  27 // a protocol with a given GUID must have
  28 // the same interface structure. While all instances of
  29 // the GUIDed Section Extraction PPI must have
  30 // the same interface structure, they do not all have
  31 // te same GUID. The GUID that is associated with
  32 // an instance of the GUIDed Section Extraction Protocol
  33 // is used to correlate it with the GUIDed section type
  34 // that it is intended to process.
  35 //
  36
  37
  38 typedef struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI   EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI;
  39
  40 //
  41 // Bit values for AuthenticationStatus
  42 //
  43 #define EFI_AUTH_STATUS_PLATFORM_OVERRIDE   0x01
  44 #define EFI_AUTH_STATUS_IMAGE_SIGNED        0x02
  45 #define EFI_AUTH_STATUS_NOT_TESTED          0x04
  46 #define EFI_AUTH_STATUS_TEST_FAILED         0x08
  47
  48 /**
  49   The ExtractSection() function processes the input section and
  50   returns a pointer to the section contents. If the section being
  51   extracted does not require processing (if the section
  52   GuidedSectionHeader.Attributes has the
  53   EFI_GUIDED_SECTION_PROCESSING_REQUIRED field cleared), then
  54   OutputBuffer is just updated to point to the start of the
  55   section's contents. Otherwise, *Buffer must be allocated
  56   from PEI permanent memory.
  57
  58   @param This                   Indicates the
  59                                 EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI instance.
  60                                 Buffer containing the input GUIDed section to be
  61                                 processed. OutputBuffer OutputBuffer is
  62                                 allocated from PEI permanent memory and contains
  63                                 the new section stream.
  64
  65   @param OutputSize             A pointer to a caller-allocated
  66                                 UINTN in which the size of *OutputBuffer
  67                                 allocation is stored. If the function
  68                                 returns anything other than EFI_SUCCESS,
  69                                 the value of OutputSize is undefined.
  70
  71   @param AuthenticationStatus   A pointer to a caller-allocated
  72                                 UINT32 that indicates the
  73                                 authentication status of the
  74                                 output buffer. If the input
  75                                 section's GuidedSectionHeader.
  76                                 Attributes field has the
  77                                 EFI_GUIDED_SECTION_AUTH_STATUS_VALID
  78                                 bit as clear,
  79                                 AuthenticationStatus must return
  80                                 zero. These bits reflect the
  81                                 status of the extraction
  82                                 operation. If the function
  83                                 returns anything other than
  84                                 EFI_SUCCESS, the value of
  85                                 AuthenticationStatus is
  86                                 undefined.
  87
  88   @retval EFI_SUCCESS           The InputSection was
  89                                 successfully processed and the
  90                                 section contents were returned.
  91
  92   @retval EFI_OUT_OF_RESOURCES  The system has insufficient
  93                                 resources to process the request.
  94
  95   @reteval EFI_INVALID_PARAMETER The GUID in InputSection does
  96                                 not match this instance of the
  97                                 GUIDed Section Extraction PPI.
  98 **/
  99 typedef
 100 EFI_STATUS
 101 (EFIAPI *EFI_PEI_EXTRACT_GUIDED_SECTION)(
 102   IN CONST  EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI *This,
 103   IN CONST  VOID                                  *InputSection,
 104   OUT       VOID                                  **OutputBuffer,
 105   OUT       UINTN                                 *OutputSize,
 106   OUT       UINT32                                *AuthenticationStatus
 107 );
 108
 109
 110
 111 /**
 112   If a GUID-defined section is encountered when doing section extraction,
 113   the PEI Foundation or the EFI_PEI_FILE_LOADER_PPI instance
 114   calls the appropriate instance of the GUIDed Section
 115   Extraction PPI to extract the section stream contained
 116   therein.
 117
 118
 119   @param ExtractSection   Takes the GUIDed section as input and
 120                           produces the section stream data. See
 121                           the ExtractSection() function
 122                           description.
 123
 124 **/
 125 struct _EFI_PEI_GUIDED_SECTION_EXTRACTION_PPI {
 126   EFI_PEI_EXTRACT_GUIDED_SECTION ExtractSection;
 127 };
 128
 129
 130
 131 #endif
 132