[mirror_edk2.git] / IntelFrameworkModulePkg / Universal / SectionExtractionDxe / SectionExtraction.h

/** @file\r
  Section Extraction Protocol implementation.\r
  \r
  Stream database is implemented as a linked list of section streams,\r
  where each stream contains a linked list of children, which may be leaves or\r
  encapsulations.  \r
  \r
  Children that are encapsulations generate new stream entries\r
  when they are created.  Streams can also be created by calls to \r
  SEP->OpenSectionStream().\r
  \r
  The database is only created far enough to return the requested data from\r
  any given stream, or to determine that the requested data is not found.\r
  \r
  If a GUIDed encapsulation is encountered, there are three possiblilites.\r
  \r
  1) A support protocol is found, in which the stream is simply processed with\r
     the support protocol.\r
     \r
  2) A support protocol is not found, but the data is available to be read\r
     without processing.  In this case, the database is built up through the\r
     recursions to return the data, and a RPN event is set that will enable\r
     the stream in question to be refreshed if and when the required section\r
     extraction protocol is published.This insures the AuthenticationStatus \r
     does not become stale in the cache.\r
     \r
  3) A support protocol is not found, and the data is not available to be read\r
     without it.  This results in EFI_PROTOCOL_ERROR.\r
\r
Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
All rights reserved. This program and the accompanying materials\r
are licensed and made available under the terms and conditions of the BSD License\r
which accompanies this distribution.  The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
**/\r
\r
#ifndef _SECION_EXTRACTION_H_\r
#define _SECION_EXTRACTION_H_\r
\r
#include <FrameworkDxe.h>\r
\r
#include <Protocol/SectionExtraction.h>\r
\r
#include <Library/BaseLib.h>\r
#include <Library/DebugLib.h>\r
#include <Library/UefiLib.h>\r
#include <Library/UefiBootServicesTableLib.h>\r
#include <Library/MemoryAllocationLib.h>\r
#include <Library/BaseMemoryLib.h>\r
#include <Protocol/Decompress.h>\r
#include <Protocol/GuidedSectionExtraction.h>\r
\r
//\r
// Local defines and typedefs\r
//\r
#define CORE_SECTION_CHILD_SIGNATURE  EFI_SIGNATURE_32('S','X','C','S')\r
#define CHILD_SECTION_NODE_FROM_LINK(Node) \\r
  CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)\r
\r
typedef struct {\r
  UINT32                      Signature;\r
  LIST_ENTRY                  Link;\r
  UINT32                      Type;\r
  UINT32                      Size;\r
  //\r
  // StreamBase + OffsetInStream == pointer to section header in stream.  The\r
  // stream base is always known when walking the sections within.\r
  //\r
  UINT32                      OffsetInStream;\r
  //\r
  // Then EncapsulatedStreamHandle below is always 0 if the section is NOT an\r
  // encapsulating section.  Otherwise, it contains the stream handle\r
  // of the encapsulated stream.  This handle is ALWAYS produced any time an\r
  // encapsulating child is encountered, irrespective of whether the\r
  // encapsulated stream is processed further.\r
  //\r
  UINTN                       EncapsulatedStreamHandle;\r
  EFI_GUID                    *EncapsulationGuid;\r
} CORE_SECTION_CHILD_NODE;\r
\r
#define CORE_SECTION_STREAM_SIGNATURE EFI_SIGNATURE_32('S','X','S','S')\r
#define STREAM_NODE_FROM_LINK(Node) \\r
  CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)\r
\r
typedef struct {\r
  UINT32                      Signature;\r
  LIST_ENTRY                  Link;\r
  UINTN                       StreamHandle;\r
  UINT8                       *StreamBuffer;\r
  UINTN                       StreamLength;\r
  LIST_ENTRY                  Children;\r
  //\r
  // Authentication status is from GUIDed encapsulations.\r
  //\r
  UINT32                      AuthenticationStatus;\r
} CORE_SECTION_STREAM_NODE;\r
\r
#define NULL_STREAM_HANDLE    0\r
\r
typedef struct {\r
  CORE_SECTION_CHILD_NODE     *ChildNode;\r
  CORE_SECTION_STREAM_NODE    *ParentStream;\r
  VOID                        *Registration;\r
  EFI_EVENT                   Event;\r
} RPN_EVENT_CONTEXT;\r
  \r
  \r
/**\r
  Create a protocol notification event and return it.\r
\r
  @param ProtocolGuid    Protocol to register notification event on.\r
  @param NotifyTpl       Maximum TPL to signal the NotifyFunction.\r
  @param NotifyFunction  EFI notification routine.\r
  @param NotifyContext   Context passed into Event when it is created.\r
  @param Registration    Registration key returned from RegisterProtocolNotify().\r
  @param SignalFlag      Boolean value to decide whether kick the event after register or not.\r
\r
  @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid\r
           is added to the system.\r
\r
**/\r
EFI_EVENT\r
CoreCreateProtocolNotifyEvent (\r
  IN EFI_GUID             *ProtocolGuid,\r
  IN EFI_TPL              NotifyTpl,\r
  IN EFI_EVENT_NOTIFY     NotifyFunction,\r
  IN VOID                 *NotifyContext,\r
  OUT VOID                **Registration,\r
  IN  BOOLEAN             SignalFlag\r
  );\r
\r
//\r
// Local prototypes\r
//\r
\r
/**\r
  Worker function.  Determine if the input stream:child matches the input type.\r
\r
  @param Stream                 Indicates the section stream associated with the child\r
  @param Child                  Indicates the child to check\r
  @param SearchType             Indicates the type of section to check against for\r
  @param SectionDefinitionGuid  Indicates the GUID to check against if the type is\r
                                EFI_SECTION_GUID_DEFINED\r
\r
  @retval TRUE                  The child matches\r
  @retval FALSE                 The child doesn't match\r
\r
**/\r
BOOLEAN\r
ChildIsType (\r
  IN CORE_SECTION_STREAM_NODE *Stream,\r
  IN CORE_SECTION_CHILD_NODE  *Child,\r
  IN EFI_SECTION_TYPE         SearchType,\r
  IN EFI_GUID                 *SectionDefinitionGuid\r
  );\r
\r
/**\r
  RPN callback function.  Removes a stale section stream and re-initializes it\r
  with an updated AuthenticationStatus.\r
\r
  @param Event               The event that fired\r
  @param RpnContext          A pointer to the context that allows us to identify\r
                             the relevent encapsulation.\r
\r
**/\r
VOID\r
EFIAPI\r
NotifyGuidedExtraction (\r
  IN   EFI_EVENT   Event,\r
  IN   VOID        *RpnContext\r
  );\r
\r
/**\r
  Worker function.  Constructor for RPN event if needed to keep AuthenticationStatus\r
  cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...\r
\r
  @param ParentStream        Indicates the parent of the ecnapsulation section (child)\r
  @param ChildNode           Indicates the child node that is the encapsulation section.\r
\r
**/\r
VOID\r
CreateGuidedExtractionRpnEvent (\r
  IN CORE_SECTION_STREAM_NODE       *ParentStream,\r
  IN CORE_SECTION_CHILD_NODE        *ChildNode\r
  );\r
\r
/**\r
  SEP member function.  This function creates and returns a new section stream\r
  handle to represent the new section stream.\r
\r
  @param This                 Indicates the calling context.\r
  @param SectionStreamLength  Size in bytes of the section stream.\r
  @param SectionStream        Buffer containing the new section stream.\r
  @param SectionStreamHandle  A pointer to a caller allocated UINTN that on output\r
                              contains the new section stream handle.\r
\r
  @retval EFI_SUCCESS           Section wase opened successfully.\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
  @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of\r
                                last section.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
OpenSectionStream (\r
  IN     EFI_SECTION_EXTRACTION_PROTOCOL           *This,\r
  IN     UINTN                                     SectionStreamLength,\r
  IN     VOID                                      *SectionStream,\r
     OUT UINTN                                     *SectionStreamHandle\r
  );\r
  \r
/**\r
  SEP member function.  Retrieves requested section from section stream.\r
\r
  @param This                  Pointer to SEP instance.\r
  @param SectionStreamHandle   The section stream from which to extract the requested\r
                               section.\r
  @param SectionType           A pointer to the type of section to search for.\r
  @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED, then\r
                               SectionDefinitionGuid indicates which of these types\r
                               of sections to search for.\r
  @param SectionInstance       Indicates which instance of the requested section to\r
                               return.\r
  @param Buffer                Double indirection to buffer.  If *Buffer is non-null on\r
                               input, then the buffer is caller allocated.  If\r
                               *Buffer is NULL, then the buffer is callee allocated.\r
                               In either case, the requried buffer size is returned\r
                               in *BufferSize.\r
  @param BufferSize            On input, indicates the size of *Buffer if *Buffer is\r
                               non-null on input.  On output, indicates the required\r
                               size (allocated size if callee allocated) of *Buffer.\r
  @param AuthenticationStatus  Indicates the authentication status of the retrieved\r
                               section.\r
\r
 \r
  @retval EFI_SUCCESS           Section was retrieved successfully\r
  @retval EFI_PROTOCOL_ERROR    A GUID defined section was encountered in the section \r
                                stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED\r
                                bit set, but there was no corresponding GUIDed Section \r
                                Extraction Protocol in the handle database.  *Buffer is \r
                                unmodified.\r
  @retval EFI_NOT_FOUND         An error was encountered when parsing the SectionStream.\r
                                This indicates the SectionStream  is not correctly \r
                                formatted.\r
  @retval EFI_NOT_FOUND         The requested section does not exist.\r
  @retval EFI_OUT_OF_RESOURCES  The system has insufficient resources to process the \r
                                request.\r
  @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
  @retval EFI_WARN_TOO_SMALL    The size of the caller allocated input buffer is \r
                                insufficient to contain the requested section.  The \r
                                input buffer is filled and contents are section contents\r
                                are truncated.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
GetSection (\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
  SEP member function.  Deletes an existing section stream\r
\r
  @param This                   Indicates the calling context.\r
  @param StreamHandleToClose    Indicates the stream to close\r
\r
  @retval EFI_SUCCESS           Section stream was closed successfully.\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
  @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of\r
                                last section.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
CloseSectionStream (\r
  IN  EFI_SECTION_EXTRACTION_PROTOCOL           *This,\r
  IN  UINTN                                     StreamHandleToClose\r
  );\r
  \r
/**\r
  Worker function.  Search stream database for requested stream handle.\r
\r
  @param SearchHandle        Indicates which stream to look for.\r
  @param FoundStream         Output pointer to the found stream.\r
\r
  @retval EFI_SUCCESS        StreamHandle was found and *FoundStream contains\r
                             the stream node.\r
  @retval EFI_NOT_FOUND      SearchHandle was not found in the stream database.\r
\r
**/\r
EFI_STATUS\r
FindStreamNode (\r
  IN  UINTN                                     SearchHandle,\r
  OUT CORE_SECTION_STREAM_NODE                  **FoundStream\r
  );\r
  \r
/**\r
  Worker function  Recursively searches / builds section stream database\r
  looking for requested section.\r
\r
\r
  @param SourceStream          Indicates the section stream in which to do the search.\r
  @param SearchType            Indicates the type of section to search for.\r
  @param SectionInstance       Indicates which instance of section to find.  This is\r
                               an in/out parameter to deal with recursions.\r
  @param SectionDefinitionGuid Guid of section definition\r
  @param FoundChild            Output indicating the child node that is found.\r
  @param FoundStream           Output indicating which section stream the child was\r
                               found in.  If this stream was generated as a result of\r
                               an encapsulation section, the streamhandle is visible\r
                               within the SEP driver only.\r
  @param AuthenticationStatus  Indicates the authentication status of the found section.\r
\r
  @retval EFI_SUCCESS          Child node was found and returned.\r
  @retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
  @retval EFI_NOT_FOUND        Requested child node does not exist.\r
  @retval EFI_PROTOCOL_ERROR   A required GUIDED section extraction protocol does not\r
                               exist\r
\r
**/\r
EFI_STATUS\r
FindChildNode (\r
  IN     CORE_SECTION_STREAM_NODE                   *SourceStream,\r
  IN     EFI_SECTION_TYPE                           SearchType,\r
  IN OUT UINTN                                      *SectionInstance,\r
  IN     EFI_GUID                                   *SectionDefinitionGuid,\r
  OUT    CORE_SECTION_CHILD_NODE                    **FoundChild,\r
  OUT    CORE_SECTION_STREAM_NODE                   **FoundStream,\r
  OUT    UINT32                                     *AuthenticationStatus\r
  );\r
  \r
/**\r
  Worker function.  Constructor for new child nodes.\r
\r
  @param Stream                Indicates the section stream in which to add the child.\r
  @param ChildOffset           Indicates the offset in Stream that is the beginning\r
                               of the child section.\r
  @param ChildNode             Indicates the Callee allocated and initialized child.\r
\r
  @retval EFI_SUCCESS          Child node was found and returned.\r
  @retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
  @retval EFI_PROTOCOL_ERROR   Encapsulation sections produce new stream handles when\r
                               the child node is created.  If the section type is GUID\r
                               defined, and the extraction GUID does not exist, and\r
                               producing the stream requires the GUID, then a protocol\r
                               error is generated and no child is produced.\r
                               Values returned by OpenSectionStreamEx.\r
\r
**/\r
EFI_STATUS\r
CreateChildNode (\r
  IN     CORE_SECTION_STREAM_NODE              *Stream,\r
  IN     UINT32                                ChildOffset,\r
     OUT CORE_SECTION_CHILD_NODE               **ChildNode\r
  );\r
  \r
/**\r
  Worker function.  Destructor for child nodes.\r
\r
  @param ChildNode           Indicates the node to destroy\r
\r
**/\r
VOID\r
FreeChildNode (\r
  IN  CORE_SECTION_CHILD_NODE                   *ChildNode\r
  );\r
  \r
/**\r
  Worker function.  Constructor for section streams.\r
\r
  @param SectionStreamLength   Size in bytes of the section stream.\r
  @param SectionStream         Buffer containing the new section stream.\r
  @param AllocateBuffer        Indicates whether the stream buffer is to be copied\r
                               or the input buffer is to be used in place.\r
  @param AuthenticationStatus  Indicates the default authentication status for the\r
                               new stream.\r
  @param SectionStreamHandle   A pointer to a caller allocated section stream handle.\r
\r
  @retval EFI_SUCCESS           Stream was added to stream database.\r
  @retval EFI_OUT_OF_RESOURCES  Memory allocation failed.\r
\r
**/\r
EFI_STATUS\r
OpenSectionStreamEx (\r
  IN     UINTN                                     SectionStreamLength,\r
  IN     VOID                                      *SectionStream,\r
  IN     BOOLEAN                                   AllocateBuffer,\r
  IN     UINT32                                    AuthenticationStatus,   \r
     OUT UINTN                                     *SectionStreamHandle\r
  );\r
  \r
/**\r
\r
  Check if a stream is valid.\r
\r
  @param SectionStream         The section stream to be checked\r
  @param SectionStreamLength   The length of section stream\r
\r
  @return The validness of a stream.\r
\r
**/\r
BOOLEAN\r
IsValidSectionStream (\r
  IN  VOID              *SectionStream,\r
  IN  UINTN             SectionStreamLength\r
  );\r
\r
#endif  // _SECTION_EXTRACTION_H_\r
Commit	Line	Data
6558a837	1	/** @file\r
797a9d67	2	Section Extraction Protocol implementation.\r
	3	\r
	4	Stream database is implemented as a linked list of section streams,\r
	5	where each stream contains a linked list of children, which may be leaves or\r
	6	encapsulations. \r
	7	\r
	8	Children that are encapsulations generate new stream entries\r
	9	when they are created. Streams can also be created by calls to \r
	10	SEP->OpenSectionStream().\r
	11	\r
	12	The database is only created far enough to return the requested data from\r
	13	any given stream, or to determine that the requested data is not found.\r
	14	\r
	15	If a GUIDed encapsulation is encountered, there are three possiblilites.\r
	16	\r
	17	1) A support protocol is found, in which the stream is simply processed with\r
	18	the support protocol.\r
	19	\r
	20	2) A support protocol is not found, but the data is available to be read\r
	21	without processing. In this case, the database is built up through the\r
	22	recursions to return the data, and a RPN event is set that will enable\r
	23	the stream in question to be refreshed if and when the required section\r
	24	extraction protocol is published.This insures the AuthenticationStatus \r
	25	does not become stale in the cache.\r
	26	\r
	27	3) A support protocol is not found, and the data is not available to be read\r
	28	without it. This results in EFI_PROTOCOL_ERROR.\r
6558a837	29	\r
	30	Copyright (c) 2006 - 2008, Intel Corporation. <BR>\r
	31	All rights reserved. This program and the accompanying materials\r
	32	are licensed and made available under the terms and conditions of the BSD License\r
	33	which accompanies this distribution. The full text of the license may be found at\r
	34	http://opensource.org/licenses/bsd-license.php\r
	35	\r
	36	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
	37	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
bcd70414	38	\r
797a9d67	39	**/\r
	40	\r
	41	#ifndef _SECION_EXTRACTION_H_\r
	42	#define _SECION_EXTRACTION_H_\r
	43	\r
	44	#include <FrameworkDxe.h>\r
	45	\r
	46	#include <Protocol/SectionExtraction.h>\r
	47	\r
	48	#include <Library/BaseLib.h>\r
	49	#include <Library/DebugLib.h>\r
	50	#include <Library/UefiLib.h>\r
	51	#include <Library/UefiBootServicesTableLib.h>\r
	52	#include <Library/MemoryAllocationLib.h>\r
	53	#include <Library/BaseMemoryLib.h>\r
	54	#include <Protocol/Decompress.h>\r
	55	#include <Protocol/GuidedSectionExtraction.h>\r
	56	\r
6558a837	57	//\r
	58	// Local defines and typedefs\r
	59	//\r
	60	#define CORE_SECTION_CHILD_SIGNATURE EFI_SIGNATURE_32('S','X','C','S')\r
	61	#define CHILD_SECTION_NODE_FROM_LINK(Node) \\r
	62	CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)\r
	63	\r
	64	typedef struct {\r
	65	UINT32 Signature;\r
	66	LIST_ENTRY Link;\r
	67	UINT32 Type;\r
	68	UINT32 Size;\r
	69	//\r
	70	// StreamBase + OffsetInStream == pointer to section header in stream. The\r
	71	// stream base is always known when walking the sections within.\r
	72	//\r
	73	UINT32 OffsetInStream;\r
	74	//\r
	75	// Then EncapsulatedStreamHandle below is always 0 if the section is NOT an\r
	76	// encapsulating section. Otherwise, it contains the stream handle\r
	77	// of the encapsulated stream. This handle is ALWAYS produced any time an\r
	78	// encapsulating child is encountered, irrespective of whether the\r
	79	// encapsulated stream is processed further.\r
	80	//\r
	81	UINTN EncapsulatedStreamHandle;\r
	82	EFI_GUID *EncapsulationGuid;\r
	83	} CORE_SECTION_CHILD_NODE;\r
	84	\r
	85	#define CORE_SECTION_STREAM_SIGNATURE EFI_SIGNATURE_32('S','X','S','S')\r
	86	#define STREAM_NODE_FROM_LINK(Node) \\r
	87	CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)\r
	88	\r
	89	typedef struct {\r
	90	UINT32 Signature;\r
	91	LIST_ENTRY Link;\r
	92	UINTN StreamHandle;\r
	93	UINT8 *StreamBuffer;\r
	94	UINTN StreamLength;\r
	95	LIST_ENTRY Children;\r
	96	//\r
	97	// Authentication status is from GUIDed encapsulations.\r
	98	//\r
	99	UINT32 AuthenticationStatus;\r
	100	} CORE_SECTION_STREAM_NODE;\r
	101	\r
	102	#define NULL_STREAM_HANDLE 0\r
	103	\r
	104	typedef struct {\r
	105	CORE_SECTION_CHILD_NODE *ChildNode;\r
	106	CORE_SECTION_STREAM_NODE *ParentStream;\r
	107	VOID *Registration;\r
	108	EFI_EVENT Event;\r
	109	} RPN_EVENT_CONTEXT;\r
	110	\r
	111	\r
	112	/**\r
	113	Create a protocol notification event and return it.\r
	114	\r
	115	@param ProtocolGuid Protocol to register notification event on.\r
	116	@param NotifyTpl Maximum TPL to signal the NotifyFunction.\r
	117	@param NotifyFunction EFI notification routine.\r
	118	@param NotifyContext Context passed into Event when it is created.\r
	119	@param Registration Registration key returned from RegisterProtocolNotify().\r
	120	@param SignalFlag Boolean value to decide whether kick the event after register or not.\r
121	\r
122	@return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid\r
123	is added to the system.\r
124	\r
125	**/\r
126	EFI_EVENT\r
127	CoreCreateProtocolNotifyEvent (\r
128	IN EFI_GUID *ProtocolGuid,\r
129	IN EFI_TPL NotifyTpl,\r
130	IN EFI_EVENT_NOTIFY NotifyFunction,\r
131	IN VOID *NotifyContext,\r
132	OUT VOID **Registration,\r
133	IN BOOLEAN SignalFlag\r
134	);\r
135	\r
136	//\r
137	// Local prototypes\r
138	//\r
139	\r
140	/**\r
141	Worker function. Determine if the input stream:child matches the input type.\r
142	\r
143	@param Stream Indicates the section stream associated with the child\r
144	@param Child Indicates the child to check\r
145	@param SearchType Indicates the type of section to check against for\r
146	@param SectionDefinitionGuid Indicates the GUID to check against if the type is\r
147	EFI_SECTION_GUID_DEFINED\r
148	\r
149	@retval TRUE The child matches\r
150	@retval FALSE The child doesn't match\r
151	\r
152	**/\r
153	BOOLEAN\r
154	ChildIsType (\r
155	IN CORE_SECTION_STREAM_NODE *Stream,\r
156	IN CORE_SECTION_CHILD_NODE *Child,\r
157	IN EFI_SECTION_TYPE SearchType,\r
158	IN EFI_GUID *SectionDefinitionGuid\r
159	);\r
160	\r
161	/**\r
162	RPN callback function. Removes a stale section stream and re-initializes it\r
163	with an updated AuthenticationStatus.\r
164	\r
165	@param Event The event that fired\r
166	@param RpnContext A pointer to the context that allows us to identify\r
167	the relevent encapsulation.\r
168	\r
169	**/\r
170	VOID\r
171	EFIAPI\r
172	NotifyGuidedExtraction (\r
173	IN EFI_EVENT Event,\r
174	IN VOID *RpnContext\r
175	);\r
176	\r
177	/**\r
178	Worker function. Constructor for RPN event if needed to keep AuthenticationStatus\r
179	cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...\r
180	\r
181	@param ParentStream Indicates the parent of the ecnapsulation section (child)\r
182	@param ChildNode Indicates the child node that is the encapsulation section.\r
183	\r
184	**/\r
185	VOID\r
186	CreateGuidedExtractionRpnEvent (\r
187	IN CORE_SECTION_STREAM_NODE *ParentStream,\r
188	IN CORE_SECTION_CHILD_NODE *ChildNode\r
189	);\r
190	\r
191	/**\r
192	SEP member function. This function creates and returns a new section stream\r
193	handle to represent the new section stream.\r
194	\r
195	@param This Indicates the calling context.\r
196	@param SectionStreamLength Size in bytes of the section stream.\r
197	@param SectionStream Buffer containing the new section stream.\r
198	@param SectionStreamHandle A pointer to a caller allocated UINTN that on output\r
199	contains the new section stream handle.\r
200	\r
201	@retval EFI_SUCCESS Section wase opened successfully.\r
202	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
203	@retval EFI_INVALID_PARAMETER Section stream does not end concident with end of\r
204	last section.\r
205	\r
206	**/\r
207	EFI_STATUS\r
208	EFIAPI\r
209	OpenSectionStream (\r
210	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
211	IN UINTN SectionStreamLength,\r
212	IN VOID *SectionStream,\r
213	OUT UINTN *SectionStreamHandle\r
214	);\r
215	\r
216	/**\r
217	SEP member function. Retrieves requested section from section stream.\r
218	\r
219	@param This Pointer to SEP instance.\r
220	@param SectionStreamHandle The section stream from which to extract the requested\r
221	section.\r
222	@param SectionType A pointer to the type of section to search for.\r
223	@param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED, then\r
224	SectionDefinitionGuid indicates which of these types\r
225	of sections to search for.\r
226	@param SectionInstance Indicates which instance of the requested section to\r
227	return.\r
228	@param Buffer Double indirection to buffer. If *Buffer is non-null on\r
229	input, then the buffer is caller allocated. If\r
230	*Buffer is NULL, then the buffer is callee allocated.\r
231	In either case, the requried buffer size is returned\r
232	in *BufferSize.\r
233	@param BufferSize On input, indicates the size of Buffer if Buffer is\r
234	non-null on input. On output, indicates the required\r
235	size (allocated size if callee allocated) of *Buffer.\r
236	@param AuthenticationStatus Indicates the authentication status of the retrieved\r
237	section.\r
238	\r
239	\r
240	@retval EFI_SUCCESS Section was retrieved successfully\r
241	@retval EFI_PROTOCOL_ERROR A GUID defined section was encountered in the section \r
242	stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED\r
243	bit set, but there was no corresponding GUIDed Section \r
244	Extraction Protocol in the handle database. *Buffer is \r
245	unmodified.\r
246	@retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream.\r
247	This indicates the SectionStream is not correctly \r
248	formatted.\r
249	@retval EFI_NOT_FOUND The requested section does not exist.\r
250	@retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process the \r
251	request.\r
252	@retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.\r
253	@retval EFI_WARN_TOO_SMALL The size of the caller allocated input buffer is \r
254	insufficient to contain the requested section. The \r
255	input buffer is filled and contents are section contents\r
256	are truncated.\r
257	\r
258	**/\r
259	EFI_STATUS\r
260	EFIAPI\r
261	GetSection (\r
262	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
263	IN UINTN SectionStreamHandle,\r
264	IN EFI_SECTION_TYPE *SectionType,\r
265	IN EFI_GUID *SectionDefinitionGuid,\r
266	IN UINTN SectionInstance,\r
267	IN VOID **Buffer,\r
268	IN OUT UINTN *BufferSize,\r
269	OUT UINT32 *AuthenticationStatus\r
270	);\r
271	\r
272	/**\r
273	SEP member function. Deletes an existing section stream\r
274	\r
275	@param This Indicates the calling context.\r
276	@param StreamHandleToClose Indicates the stream to close\r
277	\r
278	@retval EFI_SUCCESS Section stream was closed successfully.\r
279	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
280	@retval EFI_INVALID_PARAMETER Section stream does not end concident with end of\r
281	last section.\r
282	\r
283	**/\r
284	EFI_STATUS\r
285	EFIAPI\r
286	CloseSectionStream (\r
287	IN EFI_SECTION_EXTRACTION_PROTOCOL *This,\r
288	IN UINTN StreamHandleToClose\r
289	);\r
290	\r
291	/**\r
292	Worker function. Search stream database for requested stream handle.\r
293	\r
294	@param SearchHandle Indicates which stream to look for.\r
295	@param FoundStream Output pointer to the found stream.\r
296	\r
297	@retval EFI_SUCCESS StreamHandle was found and *FoundStream contains\r
298	the stream node.\r
299	@retval EFI_NOT_FOUND SearchHandle was not found in the stream database.\r
300	\r
301	**/\r
302	EFI_STATUS\r
303	FindStreamNode (\r
304	IN UINTN SearchHandle,\r
305	OUT CORE_SECTION_STREAM_NODE **FoundStream\r
306	);\r
307	\r
308	/**\r
309	Worker function Recursively searches / builds section stream database\r
310	looking for requested section.\r
311	\r
312	\r
313	@param SourceStream Indicates the section stream in which to do the search.\r
314	@param SearchType Indicates the type of section to search for.\r
315	@param SectionInstance Indicates which instance of section to find. This is\r
316	an in/out parameter to deal with recursions.\r
317	@param SectionDefinitionGuid Guid of section definition\r
318	@param FoundChild Output indicating the child node that is found.\r
319	@param FoundStream Output indicating which section stream the child was\r
320	found in. If this stream was generated as a result of\r
321	an encapsulation section, the streamhandle is visible\r
322	within the SEP driver only.\r
323	@param AuthenticationStatus Indicates the authentication status of the found section.\r
324	\r
325	@retval EFI_SUCCESS Child node was found and returned.\r
326	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
327	@retval EFI_NOT_FOUND Requested child node does not exist.\r
328	@retval EFI_PROTOCOL_ERROR A required GUIDED section extraction protocol does not\r
329	exist\r
330	\r
331	**/\r
332	EFI_STATUS\r
333	FindChildNode (\r
334	IN CORE_SECTION_STREAM_NODE *SourceStream,\r
335	IN EFI_SECTION_TYPE SearchType,\r
336	IN OUT UINTN *SectionInstance,\r
337	IN EFI_GUID *SectionDefinitionGuid,\r
338	OUT CORE_SECTION_CHILD_NODE **FoundChild,\r
339	OUT CORE_SECTION_STREAM_NODE **FoundStream,\r
340	OUT UINT32 *AuthenticationStatus\r
341	);\r
342	\r
343	/**\r
344	Worker function. Constructor for new child nodes.\r
345	\r
346	@param Stream Indicates the section stream in which to add the child.\r
347	@param ChildOffset Indicates the offset in Stream that is the beginning\r
348	of the child section.\r
349	@param ChildNode Indicates the Callee allocated and initialized child.\r
350	\r
351	@retval EFI_SUCCESS Child node was found and returned.\r
352	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
353	@retval EFI_PROTOCOL_ERROR Encapsulation sections produce new stream handles when\r
354	the child node is created. If the section type is GUID\r
355	defined, and the extraction GUID does not exist, and\r
356	producing the stream requires the GUID, then a protocol\r
357	error is generated and no child is produced.\r
358	Values returned by OpenSectionStreamEx.\r
359	\r
360	**/\r
361	EFI_STATUS\r
362	CreateChildNode (\r
363	IN CORE_SECTION_STREAM_NODE *Stream,\r
364	IN UINT32 ChildOffset,\r
365	OUT CORE_SECTION_CHILD_NODE **ChildNode\r
366	);\r
367	\r
368	/**\r
369	Worker function. Destructor for child nodes.\r
370	\r
371	@param ChildNode Indicates the node to destroy\r
372	\r
373	**/\r
374	VOID\r
375	FreeChildNode (\r
376	IN CORE_SECTION_CHILD_NODE *ChildNode\r
377	);\r
378	\r
379	/**\r
380	Worker function. Constructor for section streams.\r
381	\r
382	@param SectionStreamLength Size in bytes of the section stream.\r
383	@param SectionStream Buffer containing the new section stream.\r
384	@param AllocateBuffer Indicates whether the stream buffer is to be copied\r
385	or the input buffer is to be used in place.\r
386	@param AuthenticationStatus Indicates the default authentication status for the\r
387	new stream.\r
388	@param SectionStreamHandle A pointer to a caller allocated section stream handle.\r
389	\r
390	@retval EFI_SUCCESS Stream was added to stream database.\r
391	@retval EFI_OUT_OF_RESOURCES Memory allocation failed.\r
392	\r
393	**/\r
394	EFI_STATUS\r
395	OpenSectionStreamEx (\r
396	IN UINTN SectionStreamLength,\r
397	IN VOID *SectionStream,\r
398	IN BOOLEAN AllocateBuffer,\r
399	IN UINT32 AuthenticationStatus, \r
400	OUT UINTN *SectionStreamHandle\r
401	);\r
402	\r
403	/**\r
404	\r
405	Check if a stream is valid.\r
406	\r
407	@param SectionStream The section stream to be checked\r
408	@param SectionStreamLength The length of section stream\r
409	\r
410	@return The validness of a stream.\r
411	\r
412	**/\r
413	BOOLEAN\r
414	IsValidSectionStream (\r
415	IN VOID *SectionStream,\r
416	IN UINTN SectionStreamLength\r
417	);\r
418	\r
797a9d67	419	#endif // _SECTION_EXTRACTION_H_\r