179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing/** @file 2b4124f44f7d43ce69879f61fb910be00a6d2f7e9jcarsey This file declares Section Extraction Protocol. 379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing This interface provides a means of decoding a set of sections into a linked list of 579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing leaf sections. This provides for an extensible and flexible file format. 679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 72b3687dbb512ccd3cfbb75fa8966c3c93b3c067dhhtianCopyright (c) 2006 - 2010, Intel Corporation. All rights reserved.<BR> 8f22f941ed273753a0426d1234869857f19c28664myronporterThis program and the accompanying materials are licensed and made available under 9f22f941ed273753a0426d1234869857f19c28664myronporterthe terms and conditions of the BSD License that accompanies this distribution. 10f22f941ed273753a0426d1234869857f19c28664myronporterThe full text of the license may be found at 11f22f941ed273753a0426d1234869857f19c28664myronporterhttp://opensource.org/licenses/bsd-license.php. 12f22f941ed273753a0426d1234869857f19c28664myronporter 13f22f941ed273753a0426d1234869857f19c28664myronporterTHE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 14f22f941ed273753a0426d1234869857f19c28664myronporterWITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 1579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 1679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @par Revision Reference: 1779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing This protocol is defined in Firmware Volume Specification. 18f22f941ed273753a0426d1234869857f19c28664myronporter Version 0.9. 1979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 2079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing**/ 2179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 2279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing#ifndef _SECTION_EXTRACTION_PROTOCOL_H_ 2379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing#define _SECTION_EXTRACTION_PROTOCOL_H_ 2479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 2579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 2679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// Protocol GUID definition 2779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 2879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing#define EFI_SECTION_EXTRACTION_PROTOCOL_GUID \ 2979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing { \ 3079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 0x448F5DA4, 0x6DD7, 0x4FE1, {0x93, 0x07, 0x69, 0x22, 0x41, 0x92, 0x21, 0x5D } \ 3179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing } 3279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 3379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingtypedef struct _EFI_SECTION_EXTRACTION_PROTOCOL EFI_SECTION_EXTRACTION_PROTOCOL; 3479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 3579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 3679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// Protocol member functions 3779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 3879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing/** 3979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing Creates and returns a new section stream handle to represent the new section stream. 4079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 4179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance. 42f22f941ed273753a0426d1234869857f19c28664myronporter @param SectionStreamLength The size in bytes of the section stream. 43f22f941ed273753a0426d1234869857f19c28664myronporter @param SectionStream A buffer containing the new section stream. 4479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param SectionStreamHandle A pointer to a caller-allocated UINTN that, 4579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing on output, contains the new section stream handle. 4679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 47f22f941ed273753a0426d1234869857f19c28664myronporter @retval EFI_SUCCESS The SectionStream was successfully processed, and 4879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing the section stream handle was returned. 4979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to 5079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing process the request. 5179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_INVALID_PARAMETER The section stream may be corrupt or the value 5279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing of SectionStreamLength may be incorrect. 5379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 5479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing**/ 5579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingtypedef 5679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingEFI_STATUS 5769686d5669e0bc621ded618becf1529ce93ff1fdklu(EFIAPI *EFI_OPEN_SECTION_STREAM)( 5879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN EFI_SECTION_EXTRACTION_PROTOCOL *This, 5979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN UINTN SectionStreamLength, 6079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN VOID *SectionStream, 6179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing OUT UINTN *SectionStreamHandle 6279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing ); 6379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 6479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing/** 6579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing Reads and returns a single section from a section stream. 6679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 6779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance. 6879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param SectionStreamHandle Indicates from which section stream to read. 69f22f941ed273753a0426d1234869857f19c28664myronporter @param SectionType The pointer to an EFI_SECTION_TYPE. If SectionType == NULL, 70f22f941ed273753a0426d1234869857f19c28664myronporter the contents of the entire section stream are returned 71f22f941ed273753a0426d1234869857f19c28664myronporter in Buffer. If SectionType is not NULL, only the 72f22f941ed273753a0426d1234869857f19c28664myronporter requested section is returned. EFI_SECTION_ALL 73f22f941ed273753a0426d1234869857f19c28664myronporter matches all section types and can be used as a 74f22f941ed273753a0426d1234869857f19c28664myronporter wild card to extract all sections in order. 75f22f941ed273753a0426d1234869857f19c28664myronporter @param SectionDefinitionGuid The pointer to an EFI_GUID. If SectionType == 76f22f941ed273753a0426d1234869857f19c28664myronporter EFI_SECTION_GUID_DEFINED, SectionDefinitionGuid 77f22f941ed273753a0426d1234869857f19c28664myronporter indicates what section GUID to search for. If 78f22f941ed273753a0426d1234869857f19c28664myronporter SectionType !=EFI_SECTION_GUID_DEFINED, then 7979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing SectionDefinitionGuid is unused and is ignored. 8079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param SectionInstance Indicates which instance of the requested section 8179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing type to return when SectionType is not NULL. 8279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param SectionStreamHandle A pointer to a caller-allocated UINTN that, on output, 8379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing contains the new section stream handle. 8479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param Buffer Pointer to a pointer to a buffer in which the section 8579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing contents are returned. 86f22f941ed273753a0426d1234869857f19c28664myronporter @param BufferSize A pointer to a caller-allocated UINTN. 87f22f941ed273753a0426d1234869857f19c28664myronporter @param AuthenticationStatus A pointer to a caller-allocated UINT32 in 88f22f941ed273753a0426d1234869857f19c28664myronporter which any meta-data from encapsulation GUID-defined 89f22f941ed273753a0426d1234869857f19c28664myronporter sections is returned. 9079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 9179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_SUCCESS The SectionStream was successfully processed and 9279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing the section contents were returned in Buffer. 93f22f941ed273753a0426d1234869857f19c28664myronporter @retval EFI_PROTOCOL_ERROR A GUID-defined section was encountered inthe section 94f22f941ed273753a0426d1234869857f19c28664myronporter stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED 95f22f941ed273753a0426d1234869857f19c28664myronporter bit set, but there was no corresponding GUIDed 96f22f941ed273753a0426d1234869857f19c28664myronporter Section Extraction Protocol in the handle database. 9779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream, 98f22f941ed273753a0426d1234869857f19c28664myronporter which indicates that the SectionStream is not 99f22f941ed273753a0426d1234869857f19c28664myronporter correctly formatted. Or, the requested section does not exist. 10079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process 10179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing the request. 10279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist. 103f22f941ed273753a0426d1234869857f19c28664myronporter @retval EFI_WARN_BUFFER_TOO_SMALL The size of the input buffer is insufficient 104f22f941ed273753a0426d1234869857f19c28664myronporter to contain the requested section. The input 105f22f941ed273753a0426d1234869857f19c28664myronporter buffer is filled and section contents are truncated. 10679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 10779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing**/ 10879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingtypedef 10979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingEFI_STATUS 11069686d5669e0bc621ded618becf1529ce93ff1fdklu(EFIAPI *EFI_GET_SECTION)( 11179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN EFI_SECTION_EXTRACTION_PROTOCOL *This, 11279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN UINTN SectionStreamHandle, 11379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN EFI_SECTION_TYPE *SectionType, 11479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN EFI_GUID *SectionDefinitionGuid, 11579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN UINTN SectionInstance, 11679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN VOID **Buffer, 11779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN OUT UINTN *BufferSize, 11879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing OUT UINT32 *AuthenticationStatus 11979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing ); 12079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 12179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing/** 12279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing Deletes a section stream handle and returns all associated resources to the system. 12379964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 12479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param This Indicates the EFI_SECTION_EXTRACTION_PROTOCOL instance. 12579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @param SectionStreamHandle Indicates the section stream to close. 12679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_SUCCESS The SectionStream was successfully processed and 12779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing the section stream handle was returned. 12879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist. 12979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 13079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing**/ 13179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingtypedef 13279964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingEFI_STATUS 13369686d5669e0bc621ded618becf1529ce93ff1fdklu(EFIAPI *EFI_CLOSE_SECTION_STREAM)( 13479964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN EFI_SECTION_EXTRACTION_PROTOCOL *This, 13579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing IN UINTN SectionStreamHandle 13679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing ); 13779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 13879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 13979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// Protocol definition 14079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing// 14179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingstruct _EFI_SECTION_EXTRACTION_PROTOCOL { 1422bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 1432bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// Takes a bounded stream of sections and returns a section stream handle. 1442bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 14579964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing EFI_OPEN_SECTION_STREAM OpenSectionStream; 1462bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu 1472bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 1482bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// Given a section stream handle, retrieves the requested section and 1492bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// meta-data from the section stream. 1502bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 15179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing EFI_GET_SECTION GetSection; 1522bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu 1532bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 1542bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// Given a section stream handle, closes the section stream. 1552bbaeb0d624f1d7758edd0a8d61322af209a1b1aklu /// 15679964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing EFI_CLOSE_SECTION_STREAM CloseSectionStream; 15779964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing}; 15879964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 15979964ac84ea0ca6c68d0dea38245fa83ff1945d1bxingextern EFI_GUID gEfiSectionExtractionProtocolGuid; 16079964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing 16179964ac84ea0ca6c68d0dea38245fa83ff1945d1bxing#endif 162