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