From 6558a83700f98fce2f4369ddd9f8434c304edc1a Mon Sep 17 00:00:00 2001 From: qhuang8 Date: Tue, 20 May 2008 07:26:10 +0000 Subject: [PATCH] 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 --- .../SectionExtractionDxe/SectionExtraction.c | 432 +++++------------- .../SectionExtractionDxe/SectionExtraction.h | 382 +++++++++++++++- .../SectionExtractionDxe.inf | 20 +- 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,195 +27,19 @@ 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.
+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 // @@ -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.
+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 #include +// +// 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.
# 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] -- 2.39.2