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 - 2009, Intel Corporation
   8   All rights reserved. This program and the accompanying
   9   materials are licensed and made available under the terms and
  10   conditions of the BSD License which accompanies this
  11   distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17   Module Name:  SectionExtraction.h
  18
  19   @par Revision Reference:
  20   This protocol is defined in Firmware Volume Specification.
  21   Version 0.9
  22
  23 **/
  24
  25 #ifndef _SECTION_EXTRACTION_PROTOCOL_H_
  26 #define _SECTION_EXTRACTION_PROTOCOL_H_
  27
  28 #include <PiDxe.h>
  29 #include <Framework/FirmwareVolumeImageFormat.h>
  30
  31 //
  32 // Protocol GUID definition
  33 //
  34 #define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \
  35   { \
  36     0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \
  37   }
  38
  39 typedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL;
  40
  41 //
  42 // Protocol member functions
  43 //
  44 /**
  45   Creates and returns a new section stream handle to represent the new section stream.
  46
  47   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  48   @param  SectionStreamLength   Size in bytes of the section stream.
  49   @param  SectionStream         Buffer containing the new section stream.
  50   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that,
  51                                 on output, contains the new section stream handle.
  52
  53   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  54                                 the section stream handle was returned.
  55   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to
  56                                 process the request.
  57   @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value
  58                                 of SectionStreamLength may be incorrect.
  59
  60 **/
  61 typedef
  62 EFI_STATUS
  63 (EFIAPI *EFI_OPEN_SECTION_STREAM)(
  64   IN  EFI_SECTION_EXTRACTION_PROTOCOL                   *This,
  65   IN  UINTN                                             SectionStreamLength,
  66   IN  VOID                                              *SectionStream,
  67   OUT UINTN                                             *SectionStreamHandle
  68   );
  69
  70 /**
  71   Reads and returns a single section from a section stream.
  72
  73   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
  74   @param  SectionStreamHandle   Indicates from which section stream to read.
  75   @param  SectionType           Pointer to an EFI_SECTION_TYPE.  SectionType == NULL, the contents of the
  76                                 entire section stream are returned in Buffer.If SectionType is not NULL,
  77                                 only the  requested section is returned. EFI_SECTION_ALL matches all section
  78                                 types and can be used as a wild card to extract all sections in order.
  79   @param  SectionDefinitionGuid Pointer to an EFI_GUID.If SectionType ==
  80                                 EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid indicates what section GUID
  81                                 to search for.If SectionType !=EFI_SECTION_GUID_DEFINED, then
  82                                 SectionDefinitionGuid is unused and is ignored.
  83   @param  SectionInstance       Indicates which instance of the requested section
  84                                 type to return when SectionType is not NULL.
  85   @param  SectionStreamHandle   A pointer to a caller-allocated UINTN that, on output,
  86                                 contains the new section stream handle.
  87   @param  Buffer                Pointer to a pointer to a buffer in which the section
  88                                 contents are returned.
  89   @param  BufferSize            Pointer to a caller-allocated UINTN.
  90   @param  AuthenticationStatus  Pointer to a caller-allocated UINT32 in
  91                                 which any meta-data from encapsulation GUID-defined sections is returned.
  92
  93   @retval EFI_SUCCESS           The SectionStream was successfully processed and
  94                                 the section contents were returned in Buffer.
  95   @retval EFI_PROTOCOL_ERROR    A GUID-defined section was encountered in
  96                                 the section stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set,
  97                                 but there was no corresponding GUIDed Section Extraction Protocol in
  98                                 the handle database.
  99   @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream,
 100                                 which indicates that the SectionStream is not correctly formatted.
 101                                 Or The requested section does not exist.
 102   @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process
 103                                 the request.
 104   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 105   @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient to contain the requested
 106                                     section. The input buffer is filled and section contents are truncated.
 107
 108 **/
 109 typedef
 110 EFI_STATUS
 111 (EFIAPI *EFI_GET_SECTION)(
 112   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 113   IN UINTN                                              SectionStreamHandle,
 114   IN EFI_SECTION_TYPE                                   *SectionType,
 115   IN EFI_GUID                                           *SectionDefinitionGuid,
 116   IN UINTN                                              SectionInstance,
 117   IN VOID                                               **Buffer,
 118   IN OUT UINTN                                          *BufferSize,
 119   OUT UINT32                                            *AuthenticationStatus
 120   );
 121
 122 /**
 123   Deletes a section stream handle and returns all associated resources to the system.
 124
 125   @param  This                  Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance.
 126   @param  SectionStreamHandle   Indicates the section stream to close.
 127   @retval EFI_SUCCESS           The SectionStream was successfully processed and
 128                                 the section stream handle was returned.
 129   @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
 130
 131 **/
 132 typedef
 133 EFI_STATUS
 134 (EFIAPI *EFI_CLOSE_SECTION_STREAM)(
 135   IN EFI_SECTION_EXTRACTION_PROTOCOL                    *This,
 136   IN UINTN                                              SectionStreamHandle
 137   );
 138
 139 //
 140 // Protocol definition
 141 //
 142 struct _EFI_SECTION_EXTRACTION_PROTOCOL {
 143   ///
 144   ///  Takes a bounded stream of sections and returns a section stream handle.
 145   ///
 146   EFI_OPEN_SECTION_STREAM   OpenSectionStream;
 147
 148   ///
 149   ///  Given a section stream handle, retrieves the requested section and
 150   ///  meta-data from the section stream.
 151   ///
 152   EFI_GET_SECTION           GetSection;
 153
 154   ///
 155   ///  Given a section stream handle, closes the section stream.
 156   ///
 157   EFI_CLOSE_SECTION_STREAM  CloseSectionStream;
 158 };
 159
 160 extern EFI_GUID gEfiSectionExtractionProtocolGuid;
 161
 162 #endif