MdePkg/Include/Protocol/GuidedSectionExtaction.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 - 2007, Intel Corporation
   8   All rights reserved. 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
  66                 EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
  67
  68   @param InputSection Buffer containing the input GUIDed section
  69                       to be processed. OutputBuffer OutputBuffer
  70                       is allocated from boot services pool
  71                       memory and contains the new section
  72                       stream. The caller is responsible for
  73                       freeing this buffer.
  74
  75   @param OutputSize   A pointer to a caller-allocated UINTN in
  76                       which the size of OutputBuffer allocation
  77                       is stored. If the function returns
  78                       anything other than EFI_SUCCESS, the value
  79                       of OutputSize is undefined.
  80
  81   @param AuthenticationStatus A pointer to a caller-allocated
  82                               UINT32 that indicates the
  83                               authentication status of the
  84                               output buffer. If the input
  85                               section's
  86                               GuidedSectionHeader.Attributes
  87                               field has the
  88                               EFI_GUIDED_SECTION_AUTH_STATUS_VAL
  89                               bit as clear, AuthenticationStatus
  90                               must return zero. Both local bits
  91                               (19:16) and aggregate bits (3:0)
  92                               in AuthenticationStatus are
  93                               returned by ExtractSection().
  94                               These bits reflect the status of
  95                               the extraction operation. The bit
  96                               pattern in both regions must be
  97                               the same, as the local and
  98                               aggregate authentication statuses
  99                               have equivalent meaning at this
 100                               level. If the function returns
 101                               anything other than EFI_SUCCESS,
 102                               the value of AuthenticationStatus
 103                               is undefined.
 104
 105
 106   @retval EFI_SUCCESS The InputSection was successfully
 107                       processed and the section contents were
 108                       returned.
 109
 110   @retval EFI_OUT_OF_RESOURCES  The system has insufficient
 111                                 resources to process the
 112                                 request.
 113
 114   @retval EFI_INVALID_PARAMETER The GUID in InputSection does
 115                                 not match this instance of the
 116                                 GUIDed Section Extraction
 117                                 Protocol.
 118
 119 **/
 120 typedef
 121 EFI_STATUS
 122 (EFIAPI *EFI_EXTRACT_GUIDED_SECTION)(
 123   IN CONST  EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL  *This,
 124   IN CONST  VOID                                    *InputSection,
 125   OUT       VOID                                    **OutputBuffer,
 126   OUT       UINTN                                   *OutputSize,
 127   OUT       UINT32                                  *AuthenticationStatus
 128 );
 129
 130
 131 /**
 132
 133   Takes the GUIDed section as input and produces the section
 134   stream data. See the ExtractSection() function description.
 135
 136 **/
 137 struct _EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL {
 138   EFI_EXTRACT_GUIDED_SECTION  ExtractSection;
 139 };
 140
 141
 142 #endif