diff options
| author | qhuang8 <qhuang8@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-05-20 07:26:10 +0000 |
|---|---|---|
| committer | qhuang8 <qhuang8@6f19259b-4bc3-4df7-8a09-765794883524> | 2008-05-20 07:26:10 +0000 |
| commit | 6558a83700f98fce2f4369ddd9f8434c304edc1a (patch) | |
| tree | bd95d62896b2dab3d38437d54d2c55d36a3cc074 | |
| parent | a432c703fe9e172108f8d8d550e5fd49ce8679b6 (diff) | |
| download | edk2-platforms-6558a83700f98fce2f4369ddd9f8434c304edc1a.tar.xz | |
Add doxygen style comments for section extraction module.
git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5226 6f19259b-4bc3-4df7-8a09-765794883524
3 files changed, 498 insertions, 336 deletions
diff --git a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.c b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.c index a69ec6f440..51fd759331 100644 --- a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.c +++ b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.c @@ -1,4 +1,4 @@ -/**@file
+/** @file
Section Extraction Protocol implementation.
Stream database is implemented as a linked list of section streams,
@@ -27,196 +27,20 @@ 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, Intel Corporation
-All rights reserved. This program and the accompanying materials
-are licensed and made available under the terms and conditions of the BSD License
-which accompanies this distribution. The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+Copyright (c) 2006 - 2008, Intel Corporation. <BR>
+All rights reserved. This program and the accompanying materials
+are licensed and made available under the terms and conditions of the BSD License
+which accompanies this distribution. The full text of the license may be found at
+http://opensource.org/licenses/bsd-license.php
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
#include "SectionExtraction.h"
//
-// Local defines and typedefs
-//
-#define CORE_SECTION_CHILD_SIGNATURE EFI_SIGNATURE_32('S','X','C','S')
-#define CHILD_SECTION_NODE_FROM_LINK(Node) \
- CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)
-
-typedef struct {
- UINT32 Signature;
- LIST_ENTRY Link;
- UINT32 Type;
- UINT32 Size;
- //
- // StreamBase + OffsetInStream == pointer to section header in stream. The
- // stream base is always known when walking the sections within.
- //
- UINT32 OffsetInStream;
- //
- // Then EncapsulatedStreamHandle below is always 0 if the section is NOT an
- // encapsulating section. Otherwise, it contains the stream handle
- // of the encapsulated stream. This handle is ALWAYS produced any time an
- // encapsulating child is encountered, irrespective of whether the
- // encapsulated stream is processed further.
- //
- UINTN EncapsulatedStreamHandle;
- EFI_GUID *EncapsulationGuid;
-} CORE_SECTION_CHILD_NODE;
-
-#define CORE_SECTION_STREAM_SIGNATURE EFI_SIGNATURE_32('S','X','S','S')
-#define STREAM_NODE_FROM_LINK(Node) \
- CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)
-
-typedef struct {
- UINT32 Signature;
- LIST_ENTRY Link;
- UINTN StreamHandle;
- UINT8 *StreamBuffer;
- UINTN StreamLength;
- LIST_ENTRY Children;
- //
- // Authentication status is from GUIDed encapsulations.
- //
- UINT32 AuthenticationStatus;
-} CORE_SECTION_STREAM_NODE;
-
-#define NULL_STREAM_HANDLE 0
-
-typedef struct {
- CORE_SECTION_CHILD_NODE *ChildNode;
- CORE_SECTION_STREAM_NODE *ParentStream;
- VOID *Registration;
- EFI_EVENT Event;
-} RPN_EVENT_CONTEXT;
-
-
-EFI_EVENT
-CoreCreateProtocolNotifyEvent (
- IN EFI_GUID *ProtocolGuid,
- IN EFI_TPL NotifyTpl,
- IN EFI_EVENT_NOTIFY NotifyFunction,
- IN VOID *NotifyContext,
- OUT VOID **Registration,
- IN BOOLEAN SignalFlag
- );
-
-//
-// Local prototypes
-//
-
-STATIC
-BOOLEAN
-ChildIsType (
- IN CORE_SECTION_STREAM_NODE *Stream,
- IN CORE_SECTION_CHILD_NODE *Child,
- IN EFI_SECTION_TYPE SearchType,
- IN EFI_GUID *SectionDefinitionGuid
- );
-
-STATIC
-VOID
-EFIAPI
-NotifyGuidedExtraction (
- IN EFI_EVENT Event,
- IN VOID *RpnContext
- );
-
-STATIC
-VOID
-CreateGuidedExtractionRpnEvent (
- IN CORE_SECTION_STREAM_NODE *ParentStream,
- IN CORE_SECTION_CHILD_NODE *ChildNode
- );
-
-STATIC
-EFI_STATUS
-EFIAPI
-OpenSectionStream (
- IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
- IN UINTN SectionStreamLength,
- IN VOID *SectionStream,
- OUT UINTN *SectionStreamHandle
- );
-
-STATIC
-EFI_STATUS
-EFIAPI
-GetSection (
- IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
- 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
- );
-
-STATIC
-EFI_STATUS
-EFIAPI
-CloseSectionStream (
- IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
- IN UINTN StreamHandleToClose
- );
-
-STATIC
-EFI_STATUS
-FindStreamNode (
- IN UINTN SearchHandle,
- OUT CORE_SECTION_STREAM_NODE **FoundStream
- );
-
-STATIC
-EFI_STATUS
-FindChildNode (
- IN CORE_SECTION_STREAM_NODE *SourceStream,
- IN EFI_SECTION_TYPE SearchType,
- IN UINTN *SectionInstance,
- IN EFI_GUID *SectionDefinitionGuid,
- OUT CORE_SECTION_CHILD_NODE **FoundChild,
- OUT CORE_SECTION_STREAM_NODE **FoundStream,
- OUT UINT32 *AuthenticationStatus
- );
-
-STATIC
-EFI_STATUS
-CreateChildNode (
- IN CORE_SECTION_STREAM_NODE *Stream,
- IN UINT32 ChildOffset,
- OUT CORE_SECTION_CHILD_NODE **ChildNode
- );
-
-STATIC
-VOID
-FreeChildNode (
- IN CORE_SECTION_CHILD_NODE *ChildNode
- );
-
-STATIC
-EFI_STATUS
-OpenSectionStreamEx (
- IN UINTN SectionStreamLength,
- IN VOID *SectionStream,
- IN BOOLEAN AllocateBuffer,
- IN UINT32 AuthenticationStatus,
- OUT UINTN *SectionStreamHandle
- );
-
-STATIC
-BOOLEAN
-IsValidSectionStream (
- IN VOID *SectionStream,
- IN UINTN SectionStreamLength
- );
-
-//
// Module globals
//
LIST_ENTRY mStreamRoot = INITIALIZE_LIST_HEAD_VARIABLE (mStreamRoot);
@@ -233,8 +57,8 @@ EFI_SECTION_EXTRACTION_PROTOCOL mSectionExtraction = { Entry point of the section extraction code. Initializes an instance of the
section extraction interface and installs it on a new handle.
- @param ImageHandle EFI_HANDLE: A handle for the image that is initializing this driver
- @param SystemTable EFI_SYSTEM_TABLE: A pointer to the EFI system table
+ @param ImageHandle A handle for the image that is initializing this driver
+ @param SystemTable A pointer to the EFI system table
@retval EFI_SUCCESS Driver initialized successfully
@retval EFI_OUT_OF_RESOURCES Could not allocate needed resources
@@ -273,13 +97,12 @@ SectionExtractionEntryPoint ( @param SectionStreamHandle A pointer to a caller allocated UINTN that on output
contains the new section stream handle.
- @retval EFI_SUCCESS
- @retval EFI_OUT_OF_RESOURCES memory allocation failed.
- @retval EFI_INVALID_PARAMETER section stream does not end concident with end of
+ @retval EFI_SUCCESS Section wase opened successfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
last section.
**/
-STATIC
EFI_STATUS
EFIAPI
OpenSectionStream (
@@ -308,47 +131,46 @@ OpenSectionStream ( /**
SEP member function. Retrieves requested section from section stream.
- @param This: Pointer to SEP instance.
- @param SectionStreamHandle: The section stream from which to extract the requested
+ @param This Pointer to SEP instance.
+ @param SectionStreamHandle The section stream from which to extract the requested
section.
- @param SectionType: A pointer to the type of section to search for.
- @param SectionDefinitionGuid: If the section type is EFI_SECTION_GUID_DEFINED, then
- SectionDefinitionGuid indicates which of these types
- of sections to search for.
- @param SectionInstance: Indicates which instance of the requested section to
+ @param SectionType A pointer to the type of section to search for.
+ @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED, then
+ SectionDefinitionGuid indicates which of these types
+ of sections to search for.
+ @param SectionInstance Indicates which instance of the requested section to
return.
- @param Buffer: Double indirection to buffer. If *Buffer is non-null on
+ @param 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 requried buffer size is returned
in *BufferSize.
- @param BufferSize: On input, indicates the size of *Buffer if *Buffer is
+ @param 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.
- @param AuthenticationStatus: Indicates the authentication status of the retrieved
+ @param AuthenticationStatus Indicates the authentication status of the retrieved
section.
- @retval EFI_SUCCESS: Section was retrieved successfully
- @retval 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.
- @retval EFI_NOT_FOUND: An error was encountered when parsing the SectionStream.
- This indicates the SectionStream is not correctly
- formatted.
- @retval EFI_NOT_FOUND: The requested section does not exist.
- @retval EFI_OUT_OF_RESOURCES: The system has insufficient resources to process the
- request.
- @retval EFI_INVALID_PARAMETER: The SectionStreamHandle does not exist.
- @retval 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 contents are section contents
- are truncated.
-
-**/
-STATIC
+ @retval EFI_SUCCESS Section was retrieved successfully
+ @retval 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.
+ @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream.
+ This indicates the SectionStream is not correctly
+ formatted.
+ @retval EFI_NOT_FOUND The requested section does not exist.
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process the
+ request.
+ @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
+ @retval 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 contents are section contents
+ are truncated.
+
+**/
EFI_STATUS
EFIAPI
GetSection (
@@ -361,7 +183,6 @@ GetSection ( IN OUT UINTN *BufferSize,
OUT UINT32 *AuthenticationStatus
)
-
{
CORE_SECTION_STREAM_NODE *StreamNode;
EFI_TPL OldTpl;
@@ -448,23 +269,21 @@ GetSection_Done: /**
SEP member function. Deletes an existing section stream
- @param This - Indicates the calling context.
- @param StreamHandleToClose - Indicates the stream to close
+ @param This Indicates the calling context.
+ @param StreamHandleToClose Indicates the stream to close
- @retval EFI_SUCCESS
- @retval EFI_OUT_OF_RESOURCES - memory allocation failed.
- @retval EFI_INVALID_PARAMETER - section stream does not end concident with end of
- last section.
+ @retval EFI_SUCCESS Section stream was closed successfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
+ last section.
**/
-STATIC
EFI_STATUS
EFIAPI
CloseSectionStream (
IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
IN UINTN StreamHandleToClose
)
-
{
CORE_SECTION_STREAM_NODE *StreamNode;
EFI_TPL OldTpl;
@@ -502,17 +321,16 @@ CloseSectionStream ( /**
Worker function. Determine if the input stream:child matches the input type.
- @param Stream - Indicates the section stream associated with the child
- @param Child - Indicates the child to check
- @param SearchType - Indicates the type of section to check against for
- @param SectionDefinitionGuid - Indicates the GUID to check against if the type is
- EFI_SECTION_GUID_DEFINED
+ @param Stream Indicates the section stream associated with the child
+ @param Child Indicates the child to check
+ @param SearchType Indicates the type of section to check against for
+ @param SectionDefinitionGuid Indicates the GUID to check against if the type is
+ EFI_SECTION_GUID_DEFINED
- @retval TRUE - The child matches
- @retval FALSE - The child doesn't match
+ @retval TRUE The child matches
+ @retval FALSE The child doesn't match
**/
-STATIC
BOOLEAN
ChildIsType (
IN CORE_SECTION_STREAM_NODE *Stream,
@@ -541,26 +359,25 @@ ChildIsType ( looking for requested section.
- @param SourceStream - Indicates the section stream in which to do the search.
- @param SearchType - Indicates the type of section to search for.
- @param SectionInstance - Indicates which instance of section to find. This is
- an in/out parameter to deal with recursions.
- @param SectionDefinitionGuid - Guid of section definition
- @param FoundChild - Output indicating the child node that is found.
- @param 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.
- @param AuthenticationStatus- Indicates the authentication status of the found section.
-
- @retval EFI_SUCCESS - Child node was found and returned.
- @retval EFI_OUT_OF_RESOURCES- Memory allocation failed.
- @retval EFI_NOT_FOUND - Requested child node does not exist.
- @retval EFI_PROTOCOL_ERROR - a required GUIDED section extraction protocol does not
- exist
+ @param SourceStream Indicates the section stream in which to do the search.
+ @param SearchType Indicates the type of section to search for.
+ @param SectionInstance Indicates which instance of section to find. This is
+ an in/out parameter to deal with recursions.
+ @param SectionDefinitionGuid Guid of section definition
+ @param FoundChild Output indicating the child node that is found.
+ @param 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.
+ @param AuthenticationStatus Indicates the authentication status of the found section.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_NOT_FOUND Requested child node does not exist.
+ @retval EFI_PROTOCOL_ERROR A required GUIDED section extraction protocol does not
+ exist
**/
-STATIC
EFI_STATUS
FindChildNode (
IN CORE_SECTION_STREAM_NODE *SourceStream,
@@ -571,7 +388,6 @@ FindChildNode ( OUT CORE_SECTION_STREAM_NODE **FoundStream,
OUT UINT32 *AuthenticationStatus
)
-
{
CORE_SECTION_CHILD_NODE *CurrentChildNode;
CORE_SECTION_CHILD_NODE *RecursedChildNode;
@@ -691,22 +507,21 @@ FindChildNode ( /**
Worker function. Constructor for new child nodes.
- @param Stream - Indicates the section stream in which to add the child.
- @param ChildOffset - Indicates the offset in Stream that is the beginning
- of the child section.
- @param ChildNode - Indicates the Callee allocated and initialized child.
+ @param Stream Indicates the section stream in which to add the child.
+ @param ChildOffset Indicates the offset in Stream that is the beginning
+ of the child section.
+ @param ChildNode Indicates the Callee allocated and initialized child.
- @retval EFI_SUCCESS - Child node was found and returned.
- @retval EFI_OUT_OF_RESOURCES- Memory allocation failed.
- @retval 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.
+ @retval EFI_SUCCESS Child node was found and returned.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval 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.
**/
-STATIC
EFI_STATUS
CreateChildNode (
IN CORE_SECTION_STREAM_NODE *Stream,
@@ -969,11 +784,10 @@ CreateChildNode ( Worker function. Constructor for RPN event if needed to keep AuthenticationStatus
cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...
- @param ParentStream - Indicates the parent of the ecnapsulation section (child)
- @param ChildNode - Indicates the child node that is the encapsulation section.
+ @param ParentStream Indicates the parent of the ecnapsulation section (child)
+ @param ChildNode Indicates the child node that is the encapsulation section.
**/
-STATIC
VOID
CreateGuidedExtractionRpnEvent (
IN CORE_SECTION_STREAM_NODE *ParentStream,
@@ -1005,12 +819,11 @@ CreateGuidedExtractionRpnEvent ( RPN callback function. Removes a stale section stream and re-initializes it
with an updated AuthenticationStatus.
- @param Event - The event that fired
- @param RpnContext - A pointer to the context that allows us to identify
- the relevent encapsulation...
+ @param Event The event that fired
+ @param RpnContext A pointer to the context that allows us to identify
+ the relevent encapsulation.
-**/
-STATIC
+**/
VOID
EFIAPI
NotifyGuidedExtraction (
@@ -1077,15 +890,13 @@ NotifyGuidedExtraction ( /**
Worker function. Destructor for child nodes.
- @param ChildNode - Indicates the node to destroy
+ @param ChildNode Indicates the node to destroy
**/
-STATIC
VOID
FreeChildNode (
IN CORE_SECTION_CHILD_NODE *ChildNode
)
-
{
ASSERT (ChildNode->Signature == CORE_SECTION_CHILD_SIGNATURE);
//
@@ -1109,20 +920,18 @@ FreeChildNode ( /**
Worker function. Constructor for section streams.
- @param SectionStreamLength - Size in bytes of the section stream.
- @param SectionStream - Buffer containing the new section stream.
- @param AllocateBuffer - Indicates whether the stream buffer is to be copied
- or the input buffer is to be used in place.
- @param AuthenticationStatus- Indicates the default authentication status for the
- new stream.
- @param SectionStreamHandle - A pointer to a caller allocated section stream handle.
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param AllocateBuffer Indicates whether the stream buffer is to be copied
+ or the input buffer is to be used in place.
+ @param AuthenticationStatus Indicates the default authentication status for the
+ new stream.
+ @param SectionStreamHandle A pointer to a caller allocated section stream handle.
-
- @retval EFI_SUCCESS - Stream was added to stream database.
- @retval EFI_OUT_OF_RESOURCES - memory allocation failed.
+ @retval EFI_SUCCESS Stream was added to stream database.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
**/
-STATIC
EFI_STATUS
OpenSectionStreamEx (
IN UINTN SectionStreamLength,
@@ -1131,7 +940,6 @@ OpenSectionStreamEx ( IN UINT32 AuthenticationStatus,
OUT UINTN *SectionStreamHandle
)
-
{
CORE_SECTION_STREAM_NODE *NewStream;
EFI_TPL OldTpl;
@@ -1198,21 +1006,19 @@ OpenSectionStreamEx ( /**
Worker function. Search stream database for requested stream handle.
- @param SearchHandle - Indicates which stream to look for.
- @param FoundStream - Output pointer to the found stream.
+ @param SearchHandle Indicates which stream to look for.
+ @param FoundStream Output pointer to the found stream.
- @retval EFI_SUCCESS - StreamHandle was found and *FoundStream contains
- the stream node.
- @retval EFI_NOT_FOUND - SearchHandle was not found in the stream database.
+ @retval EFI_SUCCESS StreamHandle was found and *FoundStream contains
+ the stream node.
+ @retval EFI_NOT_FOUND SearchHandle was not found in the stream database.
**/
-STATIC
EFI_STATUS
FindStreamNode (
IN UINTN SearchHandle,
OUT CORE_SECTION_STREAM_NODE **FoundStream
)
-
{
CORE_SECTION_STREAM_NODE *StreamNode;
@@ -1237,18 +1043,17 @@ FindStreamNode ( Check if a stream is valid.
- @param SectionStream - The section stream to be checked
- @param SectionStreamLength - The length of section stream
+ @param SectionStream The section stream to be checked
+ @param SectionStreamLength The length of section stream
+
+ @return The validness of a stream.
- @return if a stream is valid.
**/
-STATIC
BOOLEAN
IsValidSectionStream (
IN VOID *SectionStream,
IN UINTN SectionStreamLength
)
-
{
UINTN TotalLength;
UINTN SectionLength;
@@ -1287,19 +1092,14 @@ IsValidSectionStream ( /**
Create a protocol notification event and return it.
- @param ProtocolGuid - Protocol to register notification event on.
-
- @param NotifyTpl - Maximum TPL to signal the NotifyFunction.
-
- @param NotifyFuncition - EFI notification routine.
-
- @param NotifyContext - Context passed into Event when it is created.
-
- @param Registration - Registration key returned from RegisterProtocolNotify().
-
- @param SignalFlag - Boolean value to decide whether kick the event after register or not.
+ @param ProtocolGuid Protocol to register notification event on.
+ @param NotifyTpl Maximum TPL to signal the NotifyFunction.
+ @param NotifyFunction EFI notification routine.
+ @param NotifyContext Context passed into Event when it is created.
+ @param Registration Registration key returned from RegisterProtocolNotify().
+ @param SignalFlag Boolean value to decide whether kick the event after register or not.
- @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
+ @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
is added to the system.
**/
diff --git a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.h b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.h index 4ec132057f..869744afee 100644 --- a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.h +++ b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtraction.h @@ -1,4 +1,4 @@ -/**@file
+/** @file
Section Extraction Protocol implementation.
Stream database is implemented as a linked list of section streams,
@@ -26,15 +26,15 @@ 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, Intel Corporation
-All rights reserved. This program and the accompanying materials
-are licensed and made available under the terms and conditions of the BSD License
-which accompanies this distribution. The full text of the license may be found at
-http://opensource.org/licenses/bsd-license.php
-
-THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
-WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
+
+Copyright (c) 2006 - 2008, Intel Corporation. <BR>
+All rights reserved. This program and the accompanying materials
+are licensed and made available under the terms and conditions of the BSD License
+which accompanies this distribution. The full text of the license may be found at
+http://opensource.org/licenses/bsd-license.php
+
+THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
+WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
**/
@@ -54,4 +54,366 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. #include <Protocol/Decompress.h>
#include <Protocol/GuidedSectionExtraction.h>
+//
+// Local defines and typedefs
+//
+#define CORE_SECTION_CHILD_SIGNATURE EFI_SIGNATURE_32('S','X','C','S')
+#define CHILD_SECTION_NODE_FROM_LINK(Node) \
+ CR (Node, CORE_SECTION_CHILD_NODE, Link, CORE_SECTION_CHILD_SIGNATURE)
+
+typedef struct {
+ UINT32 Signature;
+ LIST_ENTRY Link;
+ UINT32 Type;
+ UINT32 Size;
+ //
+ // StreamBase + OffsetInStream == pointer to section header in stream. The
+ // stream base is always known when walking the sections within.
+ //
+ UINT32 OffsetInStream;
+ //
+ // Then EncapsulatedStreamHandle below is always 0 if the section is NOT an
+ // encapsulating section. Otherwise, it contains the stream handle
+ // of the encapsulated stream. This handle is ALWAYS produced any time an
+ // encapsulating child is encountered, irrespective of whether the
+ // encapsulated stream is processed further.
+ //
+ UINTN EncapsulatedStreamHandle;
+ EFI_GUID *EncapsulationGuid;
+} CORE_SECTION_CHILD_NODE;
+
+#define CORE_SECTION_STREAM_SIGNATURE EFI_SIGNATURE_32('S','X','S','S')
+#define STREAM_NODE_FROM_LINK(Node) \
+ CR (Node, CORE_SECTION_STREAM_NODE, Link, CORE_SECTION_STREAM_SIGNATURE)
+
+typedef struct {
+ UINT32 Signature;
+ LIST_ENTRY Link;
+ UINTN StreamHandle;
+ UINT8 *StreamBuffer;
+ UINTN StreamLength;
+ LIST_ENTRY Children;
+ //
+ // Authentication status is from GUIDed encapsulations.
+ //
+ UINT32 AuthenticationStatus;
+} CORE_SECTION_STREAM_NODE;
+
+#define NULL_STREAM_HANDLE 0
+
+typedef struct {
+ CORE_SECTION_CHILD_NODE *ChildNode;
+ CORE_SECTION_STREAM_NODE *ParentStream;
+ VOID *Registration;
+ EFI_EVENT Event;
+} RPN_EVENT_CONTEXT;
+
+
+/**
+ Create a protocol notification event and return it.
+
+ @param ProtocolGuid Protocol to register notification event on.
+ @param NotifyTpl Maximum TPL to signal the NotifyFunction.
+ @param NotifyFunction EFI notification routine.
+ @param NotifyContext Context passed into Event when it is created.
+ @param Registration Registration key returned from RegisterProtocolNotify().
+ @param SignalFlag Boolean value to decide whether kick the event after register or not.
+
+ @return The EFI_EVENT that has been registered to be signaled when a ProtocolGuid
+ is added to the system.
+
+**/
+EFI_EVENT
+CoreCreateProtocolNotifyEvent (
+ IN EFI_GUID *ProtocolGuid,
+ IN EFI_TPL NotifyTpl,
+ IN EFI_EVENT_NOTIFY NotifyFunction,
+ IN VOID *NotifyContext,
+ OUT VOID **Registration,
+ IN BOOLEAN SignalFlag
+ );
+
+//
+// Local prototypes
+//
+
+/**
+ Worker function. Determine if the input stream:child matches the input type.
+
+ @param Stream Indicates the section stream associated with the child
+ @param Child Indicates the child to check
+ @param SearchType Indicates the type of section to check against for
+ @param SectionDefinitionGuid Indicates the GUID to check against if the type is
+ EFI_SECTION_GUID_DEFINED
+
+ @retval TRUE The child matches
+ @retval FALSE The child doesn't match
+
+**/
+BOOLEAN
+ChildIsType (
+ IN CORE_SECTION_STREAM_NODE *Stream,
+ IN CORE_SECTION_CHILD_NODE *Child,
+ IN EFI_SECTION_TYPE SearchType,
+ IN EFI_GUID *SectionDefinitionGuid
+ );
+
+/**
+ RPN callback function. Removes a stale section stream and re-initializes it
+ with an updated AuthenticationStatus.
+
+ @param Event The event that fired
+ @param RpnContext A pointer to the context that allows us to identify
+ the relevent encapsulation.
+
+**/
+VOID
+EFIAPI
+NotifyGuidedExtraction (
+ IN EFI_EVENT Event,
+ IN VOID *RpnContext
+ );
+
+/**
+ Worker function. Constructor for RPN event if needed to keep AuthenticationStatus
+ cache correct when a missing GUIDED_SECTION_EXTRACTION_PROTOCOL appears...
+
+ @param ParentStream Indicates the parent of the ecnapsulation section (child)
+ @param ChildNode Indicates the child node that is the encapsulation section.
+
+**/
+VOID
+CreateGuidedExtractionRpnEvent (
+ IN CORE_SECTION_STREAM_NODE *ParentStream,
+ IN CORE_SECTION_CHILD_NODE *ChildNode
+ );
+
+/**
+ SEP member function. This function creates and returns a new section stream
+ handle to represent the new section stream.
+
+ @param This Indicates the calling context.
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param SectionStreamHandle A pointer to a caller allocated UINTN that on output
+ contains the new section stream handle.
+
+ @retval EFI_SUCCESS Section wase opened successfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
+ last section.
+
+**/
+EFI_STATUS
+EFIAPI
+OpenSectionStream (
+ IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
+ IN UINTN SectionStreamLength,
+ IN VOID *SectionStream,
+ OUT UINTN *SectionStreamHandle
+ );
+
+/**
+ SEP member function. Retrieves requested section from section stream.
+
+ @param This Pointer to SEP instance.
+ @param SectionStreamHandle The section stream from which to extract the requested
+ section.
+ @param SectionType A pointer to the type of section to search for.
+ @param SectionDefinitionGuid If the section type is EFI_SECTION_GUID_DEFINED, then
+ SectionDefinitionGuid indicates which of these types
+ of sections to search for.
+ @param SectionInstance Indicates which instance of the requested section to
+ return.
+ @param 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 requried buffer size is returned
+ in *BufferSize.
+ @param 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.
+ @param AuthenticationStatus Indicates the authentication status of the retrieved
+ section.
+
+
+ @retval EFI_SUCCESS Section was retrieved successfully
+ @retval 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.
+ @retval EFI_NOT_FOUND An error was encountered when parsing the SectionStream.
+ This indicates the SectionStream is not correctly
+ formatted.
+ @retval EFI_NOT_FOUND The requested section does not exist.
+ @retval EFI_OUT_OF_RESOURCES The system has insufficient resources to process the
+ request.
+ @retval EFI_INVALID_PARAMETER The SectionStreamHandle does not exist.
+ @retval 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 contents are section contents
+ are truncated.
+
+**/
+EFI_STATUS
+EFIAPI
+GetSection (
+ IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
+ 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
+ );
+
+/**
+ SEP member function. Deletes an existing section stream
+
+ @param This Indicates the calling context.
+ @param StreamHandleToClose Indicates the stream to close
+
+ @retval EFI_SUCCESS Section stream was closed successfully.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_INVALID_PARAMETER Section stream does not end concident with end of
+ last section.
+
+**/
+EFI_STATUS
+EFIAPI
+CloseSectionStream (
+ IN EFI_SECTION_EXTRACTION_PROTOCOL *This,
+ IN UINTN StreamHandleToClose
+ );
+
+/**
+ Worker function. Search stream database for requested stream handle.
+
+ @param SearchHandle Indicates which stream to look for.
+ @param FoundStream Output pointer to the found stream.
+
+ @retval EFI_SUCCESS StreamHandle was found and *FoundStream contains
+ the stream node.
+ @retval EFI_NOT_FOUND SearchHandle was not found in the stream database.
+
+**/
+EFI_STATUS
+FindStreamNode (
+ IN UINTN SearchHandle,
+ OUT CORE_SECTION_STREAM_NODE **FoundStream
+ );
+
+/**
+ Worker function Recursively searches / builds section stream database
+ looking for requested section.
+
+
+ @param SourceStream Indicates the section stream in which to do the search.
+ @param SearchType Indicates the type of section to search for.
+ @param SectionInstance Indicates which instance of section to find. This is
+ an in/out parameter to deal with recursions.
+ @param SectionDefinitionGuid Guid of section definition
+ @param FoundChild Output indicating the child node that is found.
+ @param 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.
+ @param AuthenticationStatus Indicates the authentication status of the found section.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval EFI_NOT_FOUND Requested child node does not exist.
+ @retval EFI_PROTOCOL_ERROR A required GUIDED section extraction protocol does not
+ exist
+
+**/
+EFI_STATUS
+FindChildNode (
+ IN CORE_SECTION_STREAM_NODE *SourceStream,
+ IN EFI_SECTION_TYPE SearchType,
+ IN OUT UINTN *SectionInstance,
+ IN EFI_GUID *SectionDefinitionGuid,
+ OUT CORE_SECTION_CHILD_NODE **FoundChild,
+ OUT CORE_SECTION_STREAM_NODE **FoundStream,
+ OUT UINT32 *AuthenticationStatus
+ );
+
+/**
+ Worker function. Constructor for new child nodes.
+
+ @param Stream Indicates the section stream in which to add the child.
+ @param ChildOffset Indicates the offset in Stream that is the beginning
+ of the child section.
+ @param ChildNode Indicates the Callee allocated and initialized child.
+
+ @retval EFI_SUCCESS Child node was found and returned.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+ @retval 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.
+
+**/
+EFI_STATUS
+CreateChildNode (
+ IN CORE_SECTION_STREAM_NODE *Stream,
+ IN UINT32 ChildOffset,
+ OUT CORE_SECTION_CHILD_NODE **ChildNode
+ );
+
+/**
+ Worker function. Destructor for child nodes.
+
+ @param ChildNode Indicates the node to destroy
+
+**/
+VOID
+FreeChildNode (
+ IN CORE_SECTION_CHILD_NODE *ChildNode
+ );
+
+/**
+ Worker function. Constructor for section streams.
+
+ @param SectionStreamLength Size in bytes of the section stream.
+ @param SectionStream Buffer containing the new section stream.
+ @param AllocateBuffer Indicates whether the stream buffer is to be copied
+ or the input buffer is to be used in place.
+ @param AuthenticationStatus Indicates the default authentication status for the
+ new stream.
+ @param SectionStreamHandle A pointer to a caller allocated section stream handle.
+
+ @retval EFI_SUCCESS Stream was added to stream database.
+ @retval EFI_OUT_OF_RESOURCES Memory allocation failed.
+
+**/
+EFI_STATUS
+OpenSectionStreamEx (
+ IN UINTN SectionStreamLength,
+ IN VOID *SectionStream,
+ IN BOOLEAN AllocateBuffer,
+ IN UINT32 AuthenticationStatus,
+ OUT UINTN *SectionStreamHandle
+ );
+
+/**
+
+ Check if a stream is valid.
+
+ @param SectionStream The section stream to be checked
+ @param SectionStreamLength The length of section stream
+
+ @return The validness of a stream.
+
+**/
+BOOLEAN
+IsValidSectionStream (
+ IN VOID *SectionStream,
+ IN UINTN SectionStreamLength
+ );
+
#endif // _SECTION_EXTRACTION_H_
diff --git a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.inf b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.inf index ce43aa96c8..e8a5a99fc9 100644 --- a/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.inf +++ b/IntelFrameworkModulePkg/Universal/SectionExtractionDxe/SectionExtractionDxe.inf @@ -1,19 +1,19 @@ #/** @file
-# Section Extraction Dxe Driver.
-#
-# Status Code Architectural Protocol implementation as defined in Tiano
-# Architecture Specification. This driver has limited functionality
-# at runtime and will not log to Data Hub at runtime.
-# Copyright (c) 2006, Intel Corporation.
-#
+#
+# Section Extraction Dxe Driver.
+#
+# Section Extraction Protocol implementation as defined in Intel Framework
+# Specification.
+#
+# Copyright (c) 2006 - 2008, Intel Corporation. <BR>
# All rights reserved. This program and the accompanying materials
# are licensed and made available under the terms and conditions of the BSD License
-# which accompanies this distribution. The full text of the license may be found at
+# which accompanies this distribution. The full text of the license may be found at
# http://opensource.org/licenses/bsd-license.php
+#
# THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
# WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
-#
-#
+#
#**/
[Defines]
|