MdePkg/Include/Protocol/GuidedSectionExtraction.h

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