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