IntelFrameworkPkg/Include/Protocol/SectionExtraction.h

   1 /** @file
   2   This file declares Section Extraction Protocol.
   3
   4   This interface provides a means of decoding a set of sections into a linked list of
   5   leaf sections.  This provides for an extensible and flexible file format.
   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:
  11   This protocol is defined in Firmware Volume Specification.
  12   Version 0.9.
  13
  14 **/
  15
  16 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
  17 #define _SECTION_EXTRACTION_PROTOCOL_H_
  18
  19 //
  20 // Protocol GUID definition
  21 //
  22 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
  23   { \
  24     0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
  25   }
  26
  27 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
  28
  29 //
  30 // Protocol member functions
  31 //
  32 /**
  33   Creates and returns a new section stream handle to represent the new section stream.
  34
  35   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  36   @param  SectionStreamLength   The size in bytes of the section stream.
  37   @param  SectionStream         A buffer containing the new section stream.
  38   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,
  39                                 on output, contains the new section stream handle.
  40
  41   @retval EFI_SUCCESS           The SectionStream was successfully processed, and
  42                                 the section stream handle was returned.
  43   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to
  44                                 process the request.
  45   @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
  46                                 of SectionStreamLength may be incorrect.
  47
  48 **/
  49 typedef
  50 EFI_STATUS
  51 (EFIAPI *EFI_OPEN_SECTION_STREAM)(
  52   IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,
  53   IN  UINTN                                             SectionStreamLength,
  54   IN  VOID                                              *SectionStream,
  55   OUT UINTN                                             *SectionStreamHandle
  56   );
  57
  58 /**
  59   Reads and returns a single section from a section stream.
  60
  61   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  62   @param  SectionStreamHandle   Indicates from which section stream to read.
  63   @param  SectionType           The pointer to an EFI_SECTION_TYPE. If SectionType == NULL,
  64                                 the contents of the entire section stream are returned
  65                                 in Buffer. If SectionType is not NULL, only the
  66                                 requested section is returned. EFI_SECTION_ALL
  67                                 matches all section types and can be used as a
  68                                 wild card to extract all sections in order.
  69   @param  SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType ==
  70                                 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid
  71                                 indicates what section GUID to search for. If
  72                                 SectionType !=EFI_SECTION_GUID_DEFINED, then
  73                                 SectionDefinitionGuid is unused and is ignored.
  74   @param  SectionInstance       Indicates which instance of the requested section
  75                                 type to return when SectionType is not NULL.
  76   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,
  77                                 contains the new section stream handle.
  78   @param  Buffer                Pointer to a pointer to a buffer in which the section
  79                                 contents are returned.
  80   @param  BufferSize            A pointer to a caller-allocated UINTN.
  81   @param  AuthenticationStatus  A pointer to a caller-allocated UINT32 in
  82                                 which any meta-data from encapsulation GUID-defined
  83                                 sections is returned.
  84
  85   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  86                                 the section contents were returned in Buffer.
  87   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered inthe section
  88                                 stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED
  89                                 bit set, but there was no corresponding GUIDed
  90                                 Section Extraction Protocol in the handle database.
  91   @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,
  92                                 which indicates that the SectionStream is not
  93                                 correctly formatted. Or, the requested section does not exist.
  94   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
  95                                 the request.
  96   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
  97   @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient
  98                                     to contain the requested section. The input
  99                                     buffer is filled and section contents are truncated.
 100
 101 **/
 102 typedef
 103 EFI_STATUS
 104 (EFIAPI *EFI_GET_SECTION)(
 105   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 106   IN UINTN                                              SectionStreamHandle,
 107   IN EFI_SECTION_TYPE                                   *SectionType,
 108   IN EFI_GUID                                           *SectionDefinitionGuid,
 109   IN UINTN                                              SectionInstance,
 110   IN VOID                                               **Buffer,
 111   IN OUT UINTN                                          *BufferSize,
 112   OUT UINT32                                            *AuthenticationStatus
 113   );
 114
 115 /**
 116   Deletes a section stream handle and returns all associated resources to the system.
 117
 118   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
 119   @param  SectionStreamHandle   Indicates the section stream to close.
 120   @retval EFI_SUCCESS           The SectionStream was successfully processed and
 121                                 the section stream handle was returned.
 122   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 123
 124 **/
 125 typedef
 126 EFI_STATUS
 127 (EFIAPI *EFI_CLOSE_SECTION_STREAM)(
 128   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 129   IN UINTN                                              SectionStreamHandle
 130   );
 131
 132 //
 133 // Protocol definition
 134 //
 135 struct _EFI_SECTION_EXTRACTION_PROTOCOL {
 136   ///
 137   ///  Takes a bounded stream of sections and returns a section stream handle.
 138   ///
 139   EFI_OPEN_SECTION_STREAM   OpenSectionStream;
 140
 141   ///
 142   ///  Given a section stream handle, retrieves the requested section and
 143   ///  meta-data from the section stream.
 144   ///
 145   EFI_GET_SECTION           GetSection;
 146
 147   ///
 148   ///  Given a section stream handle, closes the section stream.
 149   ///
 150   EFI_CLOSE_SECTION_STREAM  CloseSectionStream;
 151 };
 152
 153 extern EFI_GUID gEfiSectionExtractionProtocolGuid;
 154
 155 #endif