IntelFrameworkPkg/Include/Ppi/SectionExtraction.h

   1 /** @file
   2   This file declares the Section Extraction PPI.
   3
   4   This PPI is defined in PEI CIS version 0.91. It supports encapsulating sections,
   5   such as GUIDed sections used to authenticate the file encapsulation of other domain-specific wrapping.
   6
   7 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   8 SPDX-License-Identifier: BSD-2-Clause-Patent
   9
  10 **/
  11
  12 #ifndef __SECTION_EXTRACTION_H__
  13 #define __SECTION_EXTRACTION_H__
  14
  15 #define EFI_PEI_SECTION_EXTRACTION_PPI_GUID \
  16   { \
  17     0x4F89E208, 0xE144, 0x4804, {0x9E, 0xC8, 0x0F, 0x89, 0x4F, 0x7E, 0x36, 0xD7 } \
  18   }
  19
  20 typedef struct _EFI_PEI_SECTION_EXTRACTION_PPI EFI_PEI_SECTION_EXTRACTION_PPI;
  21
  22 //
  23 // Bit values for AuthenticationStatus
  24 //
  25 #define EFI_AUTH_STATUS_PLATFORM_OVERRIDE 0x01
  26 #define EFI_AUTH_STATUS_IMAGE_SIGNED      0x02
  27 #define EFI_AUTH_STATUS_NOT_TESTED        0x04
  28 #define EFI_AUTH_STATUS_TEST_FAILED       0x08
  29
  30 /**
  31   The function is used to retrieve a section from within a section file.
  32   It will retrieve both encapsulation sections and leaf sections in their entirety,
  33   exclusive of the section header.
  34
  35   @param PeiServices            The pointer to the PEI Services Table.
  36   @param This                   Indicates the calling context
  37   @param SectionType            The pointer to an EFI_SECTION_TYPE. If
  38                                 SectionType == NULL, the contents of the entire
  39                                 section are returned in Buffer. If SectionType
  40                                 is not NULL, only the requested section is returned.
  41   @param SectionDefinitionGuid  The pointer to an EFI_GUID.
  42                                 If SectionType == EFI_SECTION_GUID_DEFINED,
  43                                 SectionDefinitionGuid indicates for which section
  44                                 GUID to search.  If SectionType != EFI_SECTION_GUID_DEFINED,
  45                                 SectionDefinitionGuid is unused and is ignored.
  46   @param SectionInstance        If SectionType is not NULL, indicates which
  47                                 instance of the requested section type to return.
  48   @param Buffer                 The pointer to a pointer to a buffer in which the
  49                                 section contents are returned.
  50   @param BufferSize             A pointer to a caller-allocated UINT32. On input,
  51                                 *BufferSize indicates the size in bytes of the
  52                                 memory region pointed to by Buffer. On output,
  53                                 *BufferSize contains the number of bytes required
  54                                 to read the section.
  55   @param AuthenticationStatus   A pointer to a caller-allocated UINT32 in
  56                                 which any metadata from encapsulating GUID-defined
  57                                 sections is returned.
  58
  59   @retval EFI_SUCCESS           The section was successfully processed, and the section
  60                                 contents were returned in Buffer.
  61   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered in
  62                                 the file with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
  63                                 bit set, but there was no corresponding GUIDed
  64                                 Section Extraction Protocol in the handle database.
  65                                 *Buffer is unmodified.
  66   @retval EFI_NOT_FOUND         The requested section does not exist.*Buffer is
  67                                 unmodified.
  68   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
  69                                 the request.
  70   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  71   @retval EFI_WARN_TOO_SMALL    The size of the input buffer is insufficient to
  72                                 contain the requested section. The input buffer
  73                                 is filled and contents are section contents are
  74                                 truncated.
  75
  76 **/
  77 typedef
  78 EFI_STATUS
  79 (EFIAPI *EFI_PEI_GET_SECTION)(
  80   IN EFI_PEI_SERVICES                         **PeiServices,
  81   IN EFI_PEI_SECTION_EXTRACTION_PPI           *This,
  82   IN EFI_SECTION_TYPE                         *SectionType,
  83   IN EFI_GUID                                 *SectionDefinitionGuid, OPTIONAL
  84   IN UINTN                                    SectionInstance,
  85   IN VOID                                     **Buffer,
  86   IN OUT UINT32                               *BufferSize,
  87   OUT UINT32                                  *AuthenticationStatus
  88   );
  89
  90 /**
  91   This PPI supports encapsulating sections, such as GUIDed sections used to
  92   authenticate the file encapsulation of other domain-specific wrapping.
  93 **/
  94 struct _EFI_PEI_SECTION_EXTRACTION_PPI {
  95   EFI_PEI_GET_SECTION GetSection;  ///< Retrieves a section from within a section file.
  96 };
  97
  98 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;
  99
 100 #endif
 101