IntelFrameworkPkg/Include/Ppi/SectionExtraction.h

   1 /** @file
   2   This file declares 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-2009, 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 **/
  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            Pointer to the PEI Services Table.
  42   @param This                   Indicates the calling context
  43   @param SectionType            Pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
  44                                 the contents of the entire section are returned in Buffer. If SectionType
  45                                 is not NULL, only the requested section is returned.
  46   @param SectionDefinitionGuid  Pointer to an EFI_GUID.
  47                                 If SectionType == EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  48                                 indicates for which section GUID to search.
  49                                 If SectionType != EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  50                                 is unused and is ignored.
  51   @param SectionInstance        If SectionType is not NULL, indicates which
  52                                 instance of the requested section type to return.
  53   @param Buffer                 Pointer to a pointer to a buffer in which the section
  54                                 contents are returned.
  55   @param BufferSize             A pointer to a caller-allocated UINT32. On input, *BufferSize
  56                                 indicates the size in bytes of the memory region pointed to by Buffer. On output,
  57                                 *BufferSize contains the number of bytes required to read the section.
  58   @param AuthenticationStatus   A pointer to a caller-allocated UINT32 in
  59                                 which any metadata from encapsulating GUID-defined sections is returned.
  60
  61   @retval EFI_SUCCESS           The section was successfully processed and the section
  62                                 contents were returned in Buffer.
  63   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered in
  64                                 the file with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set, but
  65                                 there was no corresponding GUIDed Section Extraction Protocol in the
  66                                 handle database. *Buffer is unmodified.
  67   @retval EFI_NOT_FOUND         The requested section does not exist.*Buffer is unmodified.
  68   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the request.
  69   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  70   @retval EFI_WARN_TOO_SMALL    The size of the input buffer is insufficient to
  71                                 contain the requested section. The input buffer is filled and contents are
  72                                 section contents are truncated.
  73
  74 **/
  75 typedef
  76 EFI_STATUS
  77 (EFIAPI *EFI_PEI_GET_SECTION)(
  78   IN EFI_PEI_SERVICES                         **PeiServices,
  79   IN EFI_PEI_SECTION_EXTRACTION_PPI           *This,
  80   IN EFI_SECTION_TYPE                         *SectionType,
  81   IN EFI_GUID                                 *SectionDefinitionGuid, OPTIONAL
  82   IN UINTN                                    SectionInstance,
  83   IN VOID                                     **Buffer,
  84   IN OUT UINT32                               *BufferSize,
  85   OUT UINT32                                  *AuthenticationStatus
  86   );
  87
  88 /**
  89   This PPI supports encapsulating sections, such as GUIDed sections used to
  90   authenticate the file encapsulation of other domain-specific wrapping.
  91 **/
  92 struct _EFI_PEI_SECTION_EXTRACTION_PPI {
  93   EFI_PEI_GET_SECTION GetSection;  ///< Retrieves a section from within a section file.
  94 };
  95
  96 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;
  97
  98 #endif
  99