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