#include "DxeMain.h"

Data Structures
struct	CORE_SECTION_CHILD_NODE

struct	CORE_SECTION_STREAM_NODE

struct	RPN_EVENT_CONTEXT

Macros
#define	CORE_SECTION_CHILD_SIGNATURE SIGNATURE_32('S','X','C','S')

#define	CHILD_SECTION_NODE_FROM_LINK(Node) CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)

#define	CORE_SECTION_STREAM_SIGNATURE SIGNATURE_32('S','X','S','S')

#define	STREAM_NODE_FROM_LINK(Node) CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)

#define	NULL_STREAM_HANDLE 0

Functions
EFI_STATUS EFIAPI	CustomGuidedSectionExtract (IN CONST EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL This, IN CONST VOID InputSection, OUT VOID *OutputBuffer, OUT UINTN OutputSize, OUT UINT32 *AuthenticationStatus)

EFI_STATUS EFIAPI	InitializeSectionExtraction (IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable)

BOOLEAN	IsValidSectionStream (IN VOID *SectionStream, IN UINTN SectionStreamLength)

EFI_STATUS	OpenSectionStreamEx (IN UINTN SectionStreamLength, IN VOID SectionStream, IN BOOLEAN AllocateBuffer, IN UINT32 AuthenticationStatus, OUT UINTN SectionStreamHandle)

EFI_STATUS EFIAPI	OpenSectionStream (IN UINTN SectionStreamLength, IN VOID SectionStream, OUT UINTN SectionStreamHandle)

BOOLEAN	ChildIsType (IN CORE_SECTION_STREAM_NODE Stream, IN CORE_SECTION_CHILD_NODE Child, IN EFI_SECTION_TYPE SearchType, IN EFI_GUID *SectionDefinitionGuid)

BOOLEAN	VerifyGuidedSectionGuid (IN EFI_GUID GuidedSectionGuid, OUT EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL *GuidedSectionExtraction)

VOID EFIAPI	NotifyGuidedExtraction (IN EFI_EVENT Event, IN VOID *RpnContext)

VOID	CreateGuidedExtractionRpnEvent (IN CORE_SECTION_STREAM_NODE ParentStream, IN CORE_SECTION_CHILD_NODE ChildNode)

EFI_STATUS	CreateChildNode (IN CORE_SECTION_STREAM_NODE Stream, IN UINT32 ChildOffset, OUT CORE_SECTION_CHILD_NODE *ChildNode)

EFI_STATUS	FindChildNode (IN CORE_SECTION_STREAM_NODE SourceStream, IN EFI_SECTION_TYPE SearchType, IN OUT UINTN SectionInstance, IN EFI_GUID SectionDefinitionGuid, IN UINT32 Depth, OUT CORE_SECTION_CHILD_NODE FoundChild, OUT CORE_SECTION_STREAM_NODE FoundStream, OUT UINT32 AuthenticationStatus)

EFI_STATUS	FindStreamNode (IN UINTN SearchHandle, OUT CORE_SECTION_STREAM_NODE **FoundStream)

EFI_STATUS EFIAPI	GetSection (IN UINTN SectionStreamHandle, IN EFI_SECTION_TYPE SectionType, IN EFI_GUID SectionDefinitionGuid, IN UINTN SectionInstance, IN VOID *Buffer, IN OUT UINTN BufferSize, OUT UINT32 *AuthenticationStatus, IN BOOLEAN IsFfs3Fv)

VOID	FreeChildNode (IN CORE_SECTION_CHILD_NODE *ChildNode)

EFI_STATUS EFIAPI	CloseSectionStream (IN UINTN StreamHandleToClose, IN BOOLEAN FreeStreamBuffer)

Variables
LIST_ENTRY	mStreamRoot = INITIALIZE_LIST_HEAD_VARIABLE (mStreamRoot)

EFI_HANDLE	mSectionExtractionHandle = NULL

EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL	mCustomGuidedSectionExtractionProtocol

Detailed Description

Section Extraction Protocol implementation.

Stream database is implemented as a linked list of section streams, where each stream contains a linked list of children, which may be leaves or encapsulations.

Children that are encapsulations generate new stream entries when they are created. Streams can also be created by calls to SEP->OpenSectionStream().

The database is only created far enough to return the requested data from any given stream, or to determine that the requested data is not found.

If a GUIDed encapsulation is encountered, there are three possiblilites.

1) A support protocol is found, in which the stream is simply processed with the support protocol.

2) A support protocol is not found, but the data is available to be read without processing. In this case, the database is built up through the recursions to return the data, and a RPN event is set that will enable the stream in question to be refreshed if and when the required section extraction protocol is published.This insures the AuthenticationStatus does not become stale in the cache.

3) A support protocol is not found, and the data is not available to be read without it. This results in EFI_PROTOCOL_ERROR.

Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file CoreSectionExtraction.c.

Macro Definition Documentation

◆ CHILD_SECTION_NODE_FROM_LINK

#define CHILD_SECTION_NODE_FROM_LINK ( Node ) CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)

Definition at line 41 of file CoreSectionExtraction.c.

◆ CORE_SECTION_CHILD_SIGNATURE

#define CORE_SECTION_CHILD_SIGNATURE SIGNATURE_32('S','X','C','S')

Definition at line 40 of file CoreSectionExtraction.c.

◆ CORE_SECTION_STREAM_SIGNATURE

#define CORE_SECTION_STREAM_SIGNATURE SIGNATURE_32('S','X','S','S')

Definition at line 70 of file CoreSectionExtraction.c.

◆ NULL_STREAM_HANDLE

#define NULL_STREAM_HANDLE 0

Definition at line 87 of file CoreSectionExtraction.c.

◆ STREAM_NODE_FROM_LINK

#define STREAM_NODE_FROM_LINK ( Node ) CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)

Definition at line 71 of file CoreSectionExtraction.c.

Function Documentation

◆ ChildIsType()

BOOLEAN ChildIsType	(	IN CORE_SECTION_STREAM_NODE *	Stream,
		IN CORE_SECTION_CHILD_NODE *	Child,
		IN EFI_SECTION_TYPE	SearchType,
		IN EFI_GUID *	SectionDefinitionGuid
	)

Worker function. Determine if the input stream:child matches the input type.

Parameters

Stream	Indicates the section stream associated with the child
Child	Indicates the child to check
SearchType	Indicates the type of section to check against for
SectionDefinitionGuid	Indicates the GUID to check against if the type is EFI_SECTION_GUID_DEFINED

Return values

TRUE	The child matches
FALSE	The child doesn't match

Definition at line 456 of file CoreSectionExtraction.c.

◆ CloseSectionStream()

EFI_STATUS EFIAPI CloseSectionStream	(	IN UINTN	StreamHandleToClose,
		IN BOOLEAN	FreeStreamBuffer
	)

SEP member function. Deletes an existing section stream

Parameters

StreamHandleToClose	Indicates the stream to close
FreeStreamBuffer	TRUE - Need to free stream buffer; FALSE - No need to free stream buffer.

Return values

EFI_SUCCESS	The section stream is closed sucessfully.
EFI_OUT_OF_RESOURCES	Memory allocation failed.
EFI_INVALID_PARAMETER	Section stream does not end concident with end of last section.

Definition at line 1417 of file CoreSectionExtraction.c.

◆ CreateChildNode()

EFI_STATUS CreateChildNode	(	IN CORE_SECTION_STREAM_NODE *	Stream,
		IN UINT32	ChildOffset,
		OUT CORE_SECTION_CHILD_NODE **	ChildNode
	)

Worker function. Constructor for new child nodes.

Parameters

Stream	Indicates the section stream in which to add the child.
ChildOffset	Indicates the offset in Stream that is the beginning of the child section.
ChildNode	Indicates the Callee allocated and initialized child.

Return values

EFI_SUCCESS	Child node was found and returned. EFI_OUT_OF_RESOURCES- Memory allocation failed.
EFI_PROTOCOL_ERROR	Encapsulation sections produce new stream handles when the child node is created. If the section type is GUID defined, and the extraction GUID does not exist, and producing the stream requires the GUID, then a protocol error is generated and no child is produced. Values returned by OpenSectionStreamEx.

Definition at line 665 of file CoreSectionExtraction.c.

◆ CreateGuidedExtractionRpnEvent()

VOID CreateGuidedExtractionRpnEvent	(	IN CORE_SECTION_STREAM_NODE *	ParentStream,
		IN CORE_SECTION_CHILD_NODE *	ChildNode
	)

Constructor for RPN event when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...

Parameters

ParentStream	Indicates the parent of the ecnapsulation section (child)
ChildNode	Indicates the child node that is the encapsulation section.

Definition at line 618 of file CoreSectionExtraction.c.

◆ CustomGuidedSectionExtract()

EFI_STATUS EFIAPI CustomGuidedSectionExtract	(	IN CONST EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL *	This,
		IN CONST VOID *	InputSection,
		OUT VOID **	OutputBuffer,
		OUT UINTN *	OutputSize,
		OUT UINT32 *	AuthenticationStatus
	)

The ExtractSection() function processes the input section and allocates a buffer from the pool in which it returns the section contents. If the section being extracted contains authentication information (the section's GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit set), the values returned in AuthenticationStatus must reflect the results of the authentication operation. Depending on the algorithm and size of the encapsulated data, the time that is required to do a full authentication may be prohibitively long for some classes of systems. To indicate this, use EFI_SECURITY_POLICY_PROTOCOL_GUID, which may be published by the security policy driver (see the Platform Initialization Driver Execution Environment Core Interface Specification for more details and the GUID definition). If the EFI_SECURITY_POLICY_PROTOCOL_GUID exists in the handle database, then, if possible, full authentication should be skipped and the section contents simply returned in the OutputBuffer. In this case, the EFI_AUTH_STATUS_PLATFORM_OVERRIDE bit AuthenticationStatus must be set on return. ExtractSection() is callable only from TPL_NOTIFY and below. Behavior of ExtractSection() at any EFI_TPL above TPL_NOTIFY is undefined. Type EFI_TPL is defined in RaiseTPL() in the UEFI 2.0 specification.

Parameters

This	Indicates the EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL instance.
InputSection	Buffer containing the input GUIDed section to be processed. OutputBuffer OutputBuffer is allocated from boot services pool memory and contains the new section stream. The caller is responsible for freeing this buffer.
OutputBuffer	*OutputBuffer is allocated from boot services pool memory and contains the new section stream. The caller is responsible for freeing this buffer.
OutputSize	A pointer to a caller-allocated UINTN in which the size of OutputBuffer allocation is stored. If the function returns anything other than EFI_SUCCESS, the value of OutputSize is undefined.
AuthenticationStatus	A pointer to a caller-allocated UINT32 that indicates the authentication status of the output buffer. If the input section's GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VAL bit as clear, AuthenticationStatus must return zero. Both local bits (19:16) and aggregate bits (3:0) in AuthenticationStatus are returned by ExtractSection(). These bits reflect the status of the extraction operation. The bit pattern in both regions must be the same, as the local and aggregate authentication statuses have equivalent meaning at this level. If the function returns anything other than EFI_SUCCESS, the value of AuthenticationStatus is undefined.

Return values

EFI_SUCCESS	The InputSection was successfully processed and the section contents were returned.
EFI_OUT_OF_RESOURCES	The system has insufficient resources to process the request.
EFI_INVALID_PARAMETER	The GUID in InputSection does not match this instance of the GUIDed Section Extraction Protocol.

Definition at line 1544 of file CoreSectionExtraction.c.

◆ FindChildNode()

EFI_STATUS FindChildNode	(	IN CORE_SECTION_STREAM_NODE *	SourceStream,
		IN EFI_SECTION_TYPE	SearchType,
		IN OUT UINTN *	SectionInstance,
		IN EFI_GUID *	SectionDefinitionGuid,
		IN UINT32	Depth,
		OUT CORE_SECTION_CHILD_NODE **	FoundChild,
		OUT CORE_SECTION_STREAM_NODE **	FoundStream,
		OUT UINT32 *	AuthenticationStatus
	)

Worker function Recursively searches / builds section stream database looking for requested section.

Parameters

SourceStream	Indicates the section stream in which to do the search.
SearchType	Indicates the type of section to search for.
SectionInstance	Indicates which instance of section to find. This is an in/out parameter and it is 1-based, to deal with recursions.
SectionDefinitionGuid	Guid of section definition
Depth	Nesting depth of encapsulation sections. Callers different from FindChildNode() are responsible for passing in a zero Depth.
FoundChild	Output indicating the child node that is found.
FoundStream	Output indicating which section stream the child was found in. If this stream was generated as a result of an encapsulation section, the streamhandle is visible within the SEP driver only.
AuthenticationStatus	Indicates the authentication status of the found section.

Return values

EFI_SUCCESS	Child node was found and returned. EFI_OUT_OF_RESOURCES- Memory allocation failed.
EFI_NOT_FOUND	Requested child node does not exist.
EFI_PROTOCOL_ERROR	a required GUIDED section extraction protocol does not exist
EFI_ABORTED	Recursion aborted because Depth has been greater than or equal to PcdFwVolDxeMaxEncapsulationDepth.

Definition at line 983 of file CoreSectionExtraction.c.

◆ FindStreamNode()

EFI_STATUS FindStreamNode	(	IN UINTN	SearchHandle,
		OUT CORE_SECTION_STREAM_NODE **	FoundStream
	)

Worker function. Search stream database for requested stream handle.

Parameters

SearchHandle	Indicates which stream to look for.
FoundStream	Output pointer to the found stream.

Return values

EFI_SUCCESS	StreamHandle was found and *FoundStream contains the stream node.
EFI_NOT_FOUND	SearchHandle was not found in the stream database.

Definition at line 1158 of file CoreSectionExtraction.c.

◆ FreeChildNode()

VOID FreeChildNode ( IN CORE_SECTION_CHILD_NODE * ChildNode )

Worker function. Destructor for child nodes.

Parameters

ChildNode Indicates the node to destroy

Definition at line 1374 of file CoreSectionExtraction.c.

◆ GetSection()

EFI_STATUS EFIAPI GetSection	(	IN UINTN	SectionStreamHandle,
		IN EFI_SECTION_TYPE *	SectionType,
		IN EFI_GUID *	SectionDefinitionGuid,
		IN UINTN	SectionInstance,
		IN VOID **	Buffer,
		IN OUT UINTN *	BufferSize,
		OUT UINT32 *	AuthenticationStatus,
		IN BOOLEAN	IsFfs3Fv
	)

SEP member function. Retrieves requested section from section stream.

Parameters

SectionStreamHandle	The section stream from which to extract the requested section.
SectionType	A pointer to the type of section to search for.
SectionDefinitionGuid	If the section type is EFI_SECTION_GUID_DEFINED, then SectionDefinitionGuid indicates which of these types of sections to search for.
SectionInstance	Indicates which instance of the requested section to return.
Buffer	Double indirection to buffer. If Buffer is non-null on input, then the buffer is caller allocated. If Buffer is NULL, then the buffer is callee allocated. In either case, the required buffer size is returned in BufferSize.
BufferSize	On input, indicates the size of Buffer if Buffer is non-null on input. On output, indicates the required size (allocated size if callee allocated) of Buffer.
AuthenticationStatus	A pointer to a caller-allocated UINT32 that indicates the authentication status of the output buffer. If the input section's GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear, AuthenticationStatus must return zero. Both local bits (19:16) and aggregate bits (3:0) in AuthenticationStatus are returned by ExtractSection(). These bits reflect the status of the extraction operation. The bit pattern in both regions must be the same, as the local and aggregate authentication statuses have equivalent meaning at this level. If the function returns anything other than EFI_SUCCESS, the value of *AuthenticationStatus is undefined.
IsFfs3Fv	Indicates the FV format.

Return values

EFI_SUCCESS	Section was retrieved successfully
EFI_PROTOCOL_ERROR	A GUID defined section was encountered in the section stream with its EFI_GUIDED_SECTION_PROCESSING_REQUIRED bit set, but there was no corresponding GUIDed Section Extraction Protocol in the handle database. Buffer is unmodified.
EFI_NOT_FOUND	An error was encountered when parsing the SectionStream. This indicates the SectionStream is not correctly formatted.
EFI_NOT_FOUND	The requested section does not exist.
EFI_OUT_OF_RESOURCES	The system has insufficient resources to process the request.
EFI_INVALID_PARAMETER	The SectionStreamHandle does not exist.
EFI_WARN_TOO_SMALL	The size of the caller allocated input buffer is insufficient to contain the requested section. The input buffer is filled and section contents are truncated.

Definition at line 1242 of file CoreSectionExtraction.c.

◆ InitializeSectionExtraction()

EFI_STATUS EFIAPI InitializeSectionExtraction	(	IN EFI_HANDLE	ImageHandle,
		IN EFI_SYSTEM_TABLE *	SystemTable
	)

Entry point of the section extraction code. Initializes an instance of the section extraction interface and installs it on a new handle.

Parameters

ImageHandle	A handle for the image that is initializing this driver
SystemTable	A pointer to the EFI system table

Return values

EFI_SUCCESS	Driver initialized successfully
EFI_OUT_OF_RESOURCES	Could not allocate needed resources

Definition at line 212 of file CoreSectionExtraction.c.

◆ IsValidSectionStream()

BOOLEAN IsValidSectionStream	(	IN VOID *	SectionStream,
		IN UINTN	SectionStreamLength
	)

Check if a stream is valid.

Parameters

SectionStream	The section stream to be checked
SectionStreamLength	The length of section stream

Returns: A boolean value indicating the validness of the section stream.

Definition at line 253 of file CoreSectionExtraction.c.

◆ NotifyGuidedExtraction()

VOID EFIAPI NotifyGuidedExtraction	(	IN EFI_EVENT	Event,
		IN VOID *	RpnContext
	)

RPN callback function. Initializes the section stream when GUIDED_SECTION_EXTRACTION_PROTOCOL is installed.

Parameters

Event	The event that fired
RpnContext	A pointer to the context that allows us to identify the relevent encapsulation.

Definition at line 545 of file CoreSectionExtraction.c.

◆ OpenSectionStream()

EFI_STATUS EFIAPI OpenSectionStream	(	IN UINTN	SectionStreamLength,
		IN VOID *	SectionStream,
		OUT UINTN *	SectionStreamHandle
	)

SEP member function. This function creates and returns a new section stream handle to represent the new section stream.

Parameters

SectionStreamLength	Size in bytes of the section stream.
SectionStream	Buffer containing the new section stream.
SectionStreamHandle	A pointer to a caller allocated UINTN that on output contains the new section stream handle.

Return values

EFI_SUCCESS	The section stream is created successfully.
EFI_OUT_OF_RESOURCES	memory allocation failed.
EFI_INVALID_PARAMETER	Section stream does not end concident with end of last section.

Definition at line 418 of file CoreSectionExtraction.c.

◆ OpenSectionStreamEx()

EFI_STATUS OpenSectionStreamEx	(	IN UINTN	SectionStreamLength,
		IN VOID *	SectionStream,
		IN BOOLEAN	AllocateBuffer,
		IN UINT32	AuthenticationStatus,
		OUT UINTN *	SectionStreamHandle
	)

Worker function. Constructor for section streams.

Parameters

SectionStreamLength	Size in bytes of the section stream.
SectionStream	Buffer containing the new section stream.
AllocateBuffer	Indicates whether the stream buffer is to be copied or the input buffer is to be used in place. AuthenticationStatus- Indicates the default authentication status for the new stream.
AuthenticationStatus	A pointer to a caller-allocated UINT32 that indicates the authentication status of the output buffer. If the input section's GuidedSectionHeader.Attributes field has the EFI_GUIDED_SECTION_AUTH_STATUS_VALID bit as clear, AuthenticationStatus must return zero. Both local bits (19:16) and aggregate bits (3:0) in AuthenticationStatus are returned by ExtractSection(). These bits reflect the status of the extraction operation. The bit pattern in both regions must be the same, as the local and aggregate authentication statuses have equivalent meaning at this level. If the function returns anything other than EFI_SUCCESS, the value of *AuthenticationStatus is undefined.
SectionStreamHandle	A pointer to a caller allocated section stream handle.

Return values

EFI_SUCCESS	Stream was added to stream database.
EFI_OUT_OF_RESOURCES	memory allocation failed.

Definition at line 330 of file CoreSectionExtraction.c.

◆ VerifyGuidedSectionGuid()

BOOLEAN VerifyGuidedSectionGuid	(	IN EFI_GUID *	GuidedSectionGuid,
		OUT EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL **	GuidedSectionExtraction
	)

Verify the Guided Section GUID by checking if there is the Guided Section GUID configuration table recorded the GUID itself.

Parameters

GuidedSectionGuid	The Guided Section GUID.
GuidedSectionExtraction	A pointer to the pointer to the supported Guided Section Extraction Protocol for the Guided Section.

Returns: TRUE The GuidedSectionGuid could be identified, and the pointer to the Guided Section Extraction Protocol will be returned to *GuidedSectionExtraction.; FALSE The GuidedSectionGuid could not be identified, or the Guided Section Extraction Protocol has not been installed yet.

Definition at line 499 of file CoreSectionExtraction.c.

Variable Documentation

◆ mCustomGuidedSectionExtractionProtocol

EFI_GUIDED_SECTION_EXTRACTION_PROTOCOL mCustomGuidedSectionExtractionProtocol

Initial value:

= {
  CustomGuidedSectionExtract
}

Definition at line 195 of file CoreSectionExtraction.c.

◆ mSectionExtractionHandle

EFI_HANDLE mSectionExtractionHandle = NULL

Definition at line 193 of file CoreSectionExtraction.c.

◆ mStreamRoot

LIST_ENTRY mStreamRoot = INITIALIZE_LIST_HEAD_VARIABLE (mStreamRoot)

Definition at line 191 of file CoreSectionExtraction.c.

Data Structures

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ CHILD_SECTION_NODE_FROM_LINK

◆ CORE_SECTION_CHILD_SIGNATURE

◆ CORE_SECTION_STREAM_SIGNATURE

◆ NULL_STREAM_HANDLE

◆ STREAM_NODE_FROM_LINK

Function Documentation

◆ ChildIsType()

◆ CloseSectionStream()

◆ CreateChildNode()

◆ CreateGuidedExtractionRpnEvent()

◆ CustomGuidedSectionExtract()

◆ FindChildNode()

◆ FindStreamNode()

◆ FreeChildNode()

◆ GetSection()

◆ InitializeSectionExtraction()

◆ IsValidSectionStream()

◆ NotifyGuidedExtraction()

◆ OpenSectionStream()

◆ OpenSectionStreamEx()

◆ VerifyGuidedSectionGuid()

Variable Documentation

◆ mCustomGuidedSectionExtractionProtocol

◆ mSectionExtractionHandle

◆ mStreamRoot