BaseTools/Source/C/Include/Protocol/GuidedSectionExtraction.h

   1 /** @file
   2   This file declares GUIDed section extraction protocol.
   3
   4   This interface provides a means of decoding a GUID defined encapsulation
   5   section. There may be multiple different GUIDs associated with the GUIDed
   6   section extraction protocol. That is, all instances of the GUIDed section
   7   extraction protocol must have the same interface structure.
   8
   9   @par Revision Reference: PI
  10   Version 1.00.
  11
  12   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
  13
  14   SPDX-License-Identifier: BSD-2-Clause-Patent
  15
  16 **/
  17
  18 #ifndef __EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL_H__
  19 #define __EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL_H__
  20
  21 //
  22 // Forward reference for pure ANSI compatibility
  23
  24 typedef struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL;
  25
  26
  27 /**
  28   The ExtractSection() function processes the input section and
  29   allocates a buffer from the pool in which it returns the section
  30   contents. If the section being extracted contains
  31   authentication information (the section's
  32   GuidedSectionHeader.Attributes field has the
  33   EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values
  34   returned in AuthenticationStatus must reflect the results of
  35   the authentication operation. Depending on the algorithm and
  36   size of the encapsulated data, the time that is required to do
  37   a full authentication may be prohibitively long for some
  38   classes of systems. To indicate this, use
  39   EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by
  40   the security policy driver (see the Platform Initialization
  41   Driver Execution Environment Core Interface Specification for
  42   more details and the GUID definition). If the
  43   EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle
  44   database, then, if possible, full authentication should be
  45   skipped and the section contents simply returned in the
  46   OutputBuffer. In this case, the
  47   EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus
  48   must be set on return. ExtractSection() is callable only from
  49   TPL_NOTIFY and below. Behavior of ExtractSection() at any
  50   EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is
  51   defined in RaiseTPL() in the UEFI 2.0 specification.
  52
  53
  54   @param This   Indicates the
  55                 EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
  56
  57   @param InputSection Buffer containing the input GUIDed section
  58                       to be processed. OutputBuffer OutputBuffer
  59                       is allocated from boot services pool
  60                       memory and contains the new section
  61                       stream. The caller is responsible for
  62                       freeing this buffer.
  63
  64   @param OutputSize   A pointer to a caller-allocated UINTN in
  65                       which the size of OutputBuffer allocation
  66                       is stored. If the function returns
  67                       anything other than EFI_SUCCESS, the value
  68                       of OutputSize is undefined.
  69
  70   @param AuthenticationStatus A pointer to a caller-allocated
  71                               UINT32 that indicates the
  72                               authentication status of the
  73                               output buffer. If the input
  74                               section's
  75                               GuidedSectionHeader.Attributes
  76                               field has the
  77                               EFI_GUIDED_SECTION_AUTH_STATUS_VAL
  78                               bit as clear, AuthenticationStatus
  79                               must return zero. Both local bits
  80                               (19:16) and aggregate bits (3:0)
  81                               in AuthenticationStatus are
  82                               returned by ExtractSection().
  83                               These bits reflect the status of
  84                               the extraction operation. The bit
  85                               pattern in both regions must be
  86                               the same, as the local and
  87                               aggregate authentication statuses
  88                               have equivalent meaning at this
  89                               level. If the function returns
  90                               anything other than EFI_SUCCESS,
  91                               the value of AuthenticationStatus
  92                               is undefined.
  93
  94
  95   @retval EFI_SUCCESS The InputSection was successfully
  96                       processed and the section contents were
  97                       returned.
  98
  99   @retval EFI_OUT_OF_RESOURCES  The system has insufficient
 100                                 resources to process the
 101                                 request.
 102
 103   @retval EFI_INVALID_PARAMETER The GUID in InputSection does
 104                                 not match this instance of the
 105                                 GUIDed Section Extraction
 106                                 Protocol.
 107
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI *EFI_EXTRACT_GUIDED_SECTION)(
 112   IN CONST  EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL  *This,
 113   IN CONST  VOID                                    *InputSection,
 114   OUT       VOID                                    **OutputBuffer,
 115   OUT       UINTN                                   *OutputSize,
 116   OUT       UINT32                                  *AuthenticationStatus
 117 );
 118
 119
 120 /**
 121
 122   Takes the GUIDed section as input and produces the section
 123   stream data. See the ExtractSection() function description.
 124
 125 **/
 126 struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL {
 127   EFI_EXTRACT_GUIDED_SECTION  ExtractSection;
 128 };
 129
 130 //
 131 // Protocol GUID definition. Each GUIDed section extraction protocol has the
 132 // same interface but with different GUID. All the GUIDs is defined here.
 133 // May add multiple GUIDs here.
 134 //
 135 #define EFI_CRC32_GUIDED_SECTION_EXTRACTION_PROTOCOL_GUID \
 136   { \
 137     0xFC1BCDB0, 0x7D31, 0x49aa, {0x93, 0x6A, 0xA4, 0x60, 0x0D, 0x9D, 0xD0, 0x83 } \
 138   }
 139
 140 //
 141 // may add other GUID here
 142 //
 143 extern EFI_GUID gEfiCrc32GuidedSectionExtractionProtocolGuid;
 144
 145 #endif