[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / SectionExtraction.h

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