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