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