IntelFrameworkPkg/Include/Ppi/SectionExtraction.h

   1 /** @file
   2   This file declares Section Extraction PPI.
   3   This PPI supports encapsulating sections, such as GUIDed sections used to authenticate the file
   4   encapsulation of other domain-specific wrapping.
   5
   6   Copyright (c) 2006, Intel Corporation
   7   All rights reserved. This program and the accompanying materials
   8   are licensed and made available under the terms and conditions of the BSD License
   9   which accompanies this distribution.  The full text of the license may be found at
  10   http://opensource.org/licenses/bsd-license.php
  11
  12   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15   Module Name:  SectionExtraction.h
  16
  17   @par Revision Reference:
  18   This PPI is defined in PEI CIS.
  19   Version 0.91.
  20
  21 **/
  22
  23 #ifndef __SECTION_EXTRACTION_PPI_H__
  24 #define __SECTION_EXTRACTION_PPI_H__
  25
  26 #include <PiPei.h>
  27
  28 #define EFI_PEI_SECTION_EXTRACTION_PPI_GUID \
  29   { \
  30     0x4F89E208, 0xE144, 0x4804, {0x9E, 0xC8, 0x0F, 0x89, 0x4F, 0x7E, 0x36, 0xD7 } \
  31   }
  32
  33 typedef struct _EFI_PEI_SECTION_EXTRACTION_PPI EFI_PEI_SECTION_EXTRACTION_PPI;
  34
  35 //
  36 // Bit values for AuthenticationStatus
  37 //
  38 #define EFI_PEI_AUTH_STATUS_PLATFORM_OVERRIDE 0x01
  39 #define EFI_PEI_AUTH_STATUS_IMAGE_SIGNED      0x02
  40 #define EFI_PEI_AUTH_STATUS_NOT_TESTED        0x04
  41 #define EFI_PEI_AUTH_STATUS_TEST_FAILED       0x08
  42
  43 /**
  44   The function is used to retrieve a section from within a section file.
  45   It will retrieve both encapsulation sections and leaf sections in their entirety,
  46   exclusive of the section header.
  47
  48   @param  PeiServices    Pointer to the PEI Services Table.
  49   @param  This           Indicates the calling context
  50   @param  SectionType    Pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
  51                          the contents of the entire section are returned in Buffer. If SectionType
  52                          is not NULL, only the requested section is returned.
  53   @param  SectionDefinitionGuid
  54                          Pointer to an EFI_GUID.
  55                          If SectionType == EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  56                          indicates for which section GUID to search.
  57                          If SectionType != EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  58                          is unused and is ignored.
  59   @param  SectionInstance If SectionType is not NULL, indicates which
  60                          instance of the requested section type to return.
  61   @param  Buffer         Pointer to a pointer to a buffer in which the section
  62                          contents are returned.
  63   @param  BufferSize     A pointer to a caller-allocated UINT32.On input, *BufferSize
  64                          indicates the size in bytes of the memory region pointed to by Buffer.On output,
  65                          *BufferSize contains the number of bytes required to read the section.
  66   @param  AuthenticationStatus
  67                          A pointer to a caller-allocated UINT32 in
  68                          which any metadata from encapsulating GUID-defined sections is returned.
  69
  70   @retval EFI_SUCCESS           The section was successfully processed and the section
  71                                 contents were returned in Buffer.
  72   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered in
  73                                 the file with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set, but
  74                                 there was no corresponding GUIDed Section Extraction Protocol in the
  75                                 handle database.*Buffer is unmodified.
  76   @retval EFI_NOT_FOUND         The requested section does not exist.*Buffer is unmodified.
  77   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the request.
  78   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  79   @retval EFI_WARN_TOO_SMALL    The size of the input buffer is insufficient to
  80                                 contain the requested section. The input buffer is filled and contents are
  81                                 section contents are truncated.
  82
  83 **/
  84 typedef
  85 EFI_STATUS
  86 (EFIAPI *EFI_PEI_GET_SECTION) (
  87   IN EFI_PEI_SERVICES                         **PeiServices,
  88   IN EFI_PEI_SECTION_EXTRACTION_PPI           *This,
  89   IN EFI_SECTION_TYPE                         *SectionType,
  90   IN EFI_GUID                                 *SectionDefinitionGuid, OPTIONAL
  91   IN UINTN                                    SectionInstance,
  92   IN VOID                                     **Buffer,
  93   IN OUT UINT32                               *BufferSize,
  94   OUT UINT32                                  *AuthenticationStatus
  95   );
  96
  97 /**
  98   @par Ppi Description:
  99   This PPI supports encapsulating sections, such as GUIDed sections used to
 100   authenticate the file encapsulation of other domain-specific wrapping.
 101
 102   @param GetSection
 103   Retrieves a section from within a section file.
 104
 105 **/
 106 struct _EFI_PEI_SECTION_EXTRACTION_PPI {
 107   EFI_PEI_GET_SECTION PeiGetSection;
 108 };
 109
 110 extern EFI_GUID gEfiPeiSectionExtractionPpiGuid;
 111
 112 #endif