#include <Parser/AmlMethodParser.h>
#include <AmlCoreInterface.h>
#include <AmlDbgPrint/AmlDbgPrint.h>
#include <NameSpace/AmlNameSpace.h>
#include <Parser/AmlParser.h>
#include <Tree/AmlNode.h>
#include <Tree/AmlTree.h>
#include <String/AmlString.h>

Functions
STATIC EFI_STATUS EFIAPI	AmlDeleteNameSpaceRefNode (IN AML_NAMESPACE_REF_NODE *NameSpaceRefNode)

EFI_STATUS EFIAPI	AmlDeleteNameSpaceRefList (IN LIST_ENTRY *NameSpaceRefList)

STATIC EFI_STATUS EFIAPI	AmlCreateMethodRefNode (IN CONST AML_OBJECT_NODE ObjectNode, IN CONST CHAR8 RawAbsolutePath, IN UINT32 RawAbsolutePathSize, OUT AML_NAMESPACE_REF_NODE **NameSpaceRefNodePtr)

VOID EFIAPI	AmlDbgPrintNameSpaceRefList (IN CONST LIST_ENTRY *NameSpaceRefList)

STATIC EFI_STATUS EFIAPI	AmlInitRawPathBStream (IN CONST AML_STREAM FStream, OUT AML_STREAM RawPathNameBStream)

STATIC EFI_STATUS EFIAPI	AmlGetFirstNamedAncestorNode (IN CONST AML_NODE_HEADER Node, OUT AML_NODE_HEADER *OutNamedNode)

STATIC EFI_STATUS EFIAPI	AmlBuildRawMethodAbsolutePath (IN CONST AML_NODE_HEADER ParentNode, IN CONST AML_STREAM PathnameFStream, IN OUT AML_STREAM *AbsolutePathBStream)

STATIC EFI_STATUS EFIAPI	AmlCompareRawNameString (IN CONST AML_STREAM RawFStream1, IN CONST AML_STREAM RawFStream2, OUT UINT32 *CompareCount)

STATIC EFI_STATUS EFIAPI	AmlResolveAliasMethod (IN CONST AML_OBJECT_NODE AliasNode, IN CONST LIST_ENTRY NameSpaceRefList, OUT AML_NAMESPACE_REF_NODE **OutNameSpaceRefNode)

STATIC EFI_STATUS EFIAPI	AmlFindMethodDefinition (IN CONST AML_STREAM RawAbsolutePathFStream, IN CONST AML_STREAM RawPathNameBStream, IN CONST LIST_ENTRY NameSpaceRefList, OUT AML_NAMESPACE_REF_NODE *OutNameSpaceRefNode)

EFI_STATUS EFIAPI	AmlIsMethodInvocation (IN CONST AML_NODE_HEADER ParentNode, IN CONST AML_STREAM FStream, IN CONST LIST_ENTRY NameSpaceRefList, OUT AML_NAMESPACE_REF_NODE *OutNameSpaceRefNode)

EFI_STATUS EFIAPI	AmlAddNameSpaceReference (IN CONST AML_OBJECT_NODE Node, IN OUT LIST_ENTRY NameSpaceRefList)

EFI_STATUS EFIAPI	AmlCreateMethodInvocationNode (IN CONST AML_NAMESPACE_REF_NODE NameSpaceRefNode, IN AML_DATA_NODE MethodInvocationName, OUT AML_OBJECT_NODE **MethodInvocationNodePtr)

EFI_STATUS EFIAPI	AmlGetMethodInvocationArgCount (IN CONST AML_OBJECT_NODE MethodInvocationNode, OUT BOOLEAN IsMethodInvocation, OUT UINT8 *ArgCount)

Detailed Description

AML Method Parser.

SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file AmlMethodParser.c.

Function Documentation

◆ AmlAddNameSpaceReference()

EFI_STATUS EFIAPI AmlAddNameSpaceReference	(	IN CONST AML_OBJECT_NODE *	Node,
		IN OUT LIST_ENTRY *	NameSpaceRefList
	)

Create a namespace reference node and add it to the NameSpaceRefList.

When a namespace node is encountered, the namespace it defines must be associated to the node. This allow to keep track of the nature of each name present in the AML namespace.

In the end, this allows to recognize method invocations and parse the right number of arguments after the method name.

Parameters

[in]	Node	Namespace node.
[in,out]	NameSpaceRefList	List of namespace reference nodes.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 1130 of file AmlMethodParser.c.

◆ AmlBuildRawMethodAbsolutePath()

STATIC EFI_STATUS EFIAPI AmlBuildRawMethodAbsolutePath	(	IN CONST AML_NODE_HEADER *	ParentNode,
		IN CONST AML_STREAM *	PathnameFStream,
		IN OUT AML_STREAM *	AbsolutePathBStream
	)

From a ParentNode and a forward stream pointing to a relative path, build a raw AML absolute path and return it in a backward stream.

No memory is allocated in this function, the out stream must be initialized with a buffer long enough to hold any raw absolute AML path.

Parameters

[in]	ParentNode	Parent node of the namespace node from which the absolute path is built. ParentNode isn't necessarily a namespace node. Must be a root or an object node.
[in]	PathnameFStream	Forward stream pointing to the beginning of a pathname (any NameString). The stream must not be at its end.
[in,out]	AbsolutePathBStream	Backward stream where the raw absolute path is written. The stream must be already initialized. The stream must not be at its end.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_BUFFER_TOO_SMALL	No space left in the buffer.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 388 of file AmlMethodParser.c.

◆ AmlCompareRawNameString()

STATIC EFI_STATUS EFIAPI AmlCompareRawNameString	(	IN CONST AML_STREAM *	RawFStream1,
		IN CONST AML_STREAM *	RawFStream2,
		OUT UINT32 *	CompareCount
	)

Compare two raw NameStrings stored in forward streams. Compare them NameSeg by NameSeg (a NameSeg is 4 bytes long).

The two raw NameStrings can be of different size.

Parameters

[in]	RawFStream1	First forward stream to compare. Points to the beginning of the raw NameString.
[in]	RawFStream2	Second forward stream to compare. Points to the beginning of the raw NameString.
[out]	CompareCount	Count of identic bytes. Must be a multiple of 4 (size of a NameSeg).

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 496 of file AmlMethodParser.c.

◆ AmlCreateMethodInvocationNode()

EFI_STATUS EFIAPI AmlCreateMethodInvocationNode	(	IN CONST AML_NAMESPACE_REF_NODE *	NameSpaceRefNode,
		IN AML_DATA_NODE *	MethodInvocationName,
		OUT AML_OBJECT_NODE **	MethodInvocationNodePtr
	)

Create a method invocation node.

The AML grammar does not attribute an OpCode/SubOpCode couple for method invocations. This library is representing method invocations as if they had one.

The AML encoding for method invocations in the ACPI specification 6.3 is: MethodInvocation := NameString TermArgList In this library, it is: MethodInvocation := MethodInvocationOp NameString ArgumentCount TermArgList ArgumentCount := ByteData

When computing the size of a tree or serializing it, the additional data is not taken into account (i.e. the MethodInvocationOp and the ArgumentCount).

Method invocation nodes have the AML_METHOD_INVOVATION attribute.

Parameters

[in]	NameSpaceRefNode	NameSpaceRef node pointing to the the definition of the invoked method.
[in]	MethodInvocationName	Data node containing the method invocation name.
[out]	MethodInvocationNodePtr	Created method invocation node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Could not allocate memory.

Definition at line 1302 of file AmlMethodParser.c.

◆ AmlCreateMethodRefNode()

STATIC EFI_STATUS EFIAPI AmlCreateMethodRefNode	(	IN CONST AML_OBJECT_NODE *	ObjectNode,
		IN CONST CHAR8 *	RawAbsolutePath,
		IN UINT32	RawAbsolutePathSize,
		OUT AML_NAMESPACE_REF_NODE **	NameSpaceRefNodePtr
	)

Create an AML_NAMESPACE_REF_NODE.

A Buffer is allocated to store the raw AML absolute path.

Parameters

[in]	ObjectNode	Node being part of the namespace. Must be have the AML_IN_NAMESPACE attribute.
[in]	RawAbsolutePath	AML raw absolute path of the ObjectNode. A raw NameString is a concatenated list of 4 chars long names.
[in]	RawAbsolutePathSize	Size of the RawAbsolutePath buffer.
[out]	NameSpaceRefNodePtr	The created AML_METHOD_REF_NODE.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Could not allocate memory.

Definition at line 108 of file AmlMethodParser.c.

◆ AmlDbgPrintNameSpaceRefList()

VOID EFIAPI AmlDbgPrintNameSpaceRefList ( IN CONST LIST_ENTRY * NameSpaceRefList )

Print the list of raw absolute paths of the NameSpace reference list.

Parameters

[in] NameSpaceRefList List of NameSpace reference nodes.

Definition at line 159 of file AmlMethodParser.c.

◆ AmlDeleteNameSpaceRefList()

EFI_STATUS EFIAPI AmlDeleteNameSpaceRefList ( IN LIST_ENTRY * NameSpaceRefList )

Delete a list of namespace reference nodes.

Parameters

[in] NameSpaceRefList List of namespace reference nodes.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 61 of file AmlMethodParser.c.

◆ AmlDeleteNameSpaceRefNode()

STATIC EFI_STATUS EFIAPI AmlDeleteNameSpaceRefNode ( IN AML_NAMESPACE_REF_NODE * NameSpaceRefNode )

Delete a namespace reference node and its pathname.

It is the caller's responsibility to check the NameSpaceRefNode has been removed from any list the node is part of.

Parameters

[in] NameSpaceRefNode Pointer to an AML_NAMESPACE_REF_NODE.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 32 of file AmlMethodParser.c.

◆ AmlFindMethodDefinition()

STATIC EFI_STATUS EFIAPI AmlFindMethodDefinition	(	IN CONST AML_STREAM *	RawAbsolutePathFStream,
		IN CONST AML_STREAM *	RawPathNameBStream,
		IN CONST LIST_ENTRY *	NameSpaceRefList,
		OUT AML_NAMESPACE_REF_NODE **	OutNameSpaceRefNode
	)

Iterate through the MethodList to find the best namespace resolution. If the pathname resolves to a method definition, returns it.

For instance, if the AML namespace is: \ -MET0 <- Device definition, absolute path: \MET0 -AAAA -MET0 <- Method definition, absolute path: \AAAA.MET0 -MET1 <- Method definition, absolute path: \AAAA.MET1 -BBBB -CCCC -DDDD -MET0 <- Method definition, absolute path: \AAAA.BBBB.CCCC.DDDD.MET0

The list of the available pathnames is: [NameSpaceRefList]

\MET0 <- Device definition
\AAAA
\AAAA.MET0 <- Method definition
\AAAA.MET1 <- Method definition
\AAAA.BBBB
\AAAA.BBBB.CCCC
\AAAA.BBBB.CCCC.DDDD
\AAAA.BBBB.CCCC.DDDD.MET0 <- Method definition

Depending on where the method invocation is done, the method definition referenced changes. If the method call "MET0" is done from \AAAA.BBBB.CCCC:

Identify which pathnames end with "MET0":
- \MET0 <- Device definition
- \AAAA.MET0 <- Method definition
- \AAAA.BBBB.CCCC.DDDD.MET0 <- Method definition
Resolve the method invocation:
- \AAAA.MET0 <- Method definition
\AAAA.MET0 is a method definition, so return the corresponding reference node.

Parameters

[in]	RawAbsolutePathFStream	Forward stream pointing to a raw absolute path. The stream must not be at its end.
[in]	RawPathNameBStream	Backward stream pointing to a raw pathname. This raw pathname is the raw NameString of namespace node. The stream must not be at its end.
[in]	NameSpaceRefList	List of NameSpaceRef nodes.
[out]	OutNameSpaceRefNode	If the two input paths are referencing a method definition, returns the corresponding NameSpaceRef node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 724 of file AmlMethodParser.c.

◆ AmlGetFirstNamedAncestorNode()

STATIC EFI_STATUS EFIAPI AmlGetFirstNamedAncestorNode	(	IN CONST AML_NODE_HEADER *	Node,
		OUT AML_NODE_HEADER **	OutNamedNode
	)

Get the first node in the ParentNode branch that is part of the AML namespace and has its name defined.

This is different from getting the first namespace node. This function is necessary because an absolute path is built while the tree is not complete yet. The parsing is ongoing.

For instance, the ASL statement "CreateXXXField ()" adds a field in the AML namespace, but the name it defines is the last fixed argument of the corresponding object. If an AML path is referenced in its first fixed argument, it is not possible to resolve the name of the CreateXXXField object. However, the AML path is not part of the scope created by the CreateXXXField object, so this scope can be skipped.

In the following ASL code, the method invocation to MET0 is done in the "CreateField" statement. The "CreateField" statement defines the "FIEL" path in the AML namespace. However, MET0 must be not be resolved in the "CreateField" object scope. It needs to be resolved in its parent. ASL code: Method (MET0, 0,,, BuffObj) { Return (Buffer (0x1000) {}) } CreateField (MET0(), 0x100, 0x4, FIEL)

Parameters

[in]	Node	Node to get the first named node from, in its hierarchy.
[out]	OutNamedNode	First named node in Node's hierarchy.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 317 of file AmlMethodParser.c.

◆ AmlGetMethodInvocationArgCount()

EFI_STATUS EFIAPI AmlGetMethodInvocationArgCount	(	IN CONST AML_OBJECT_NODE *	MethodInvocationNode,
		OUT BOOLEAN *	IsMethodInvocation,
		OUT UINT8 *	ArgCount
	)

Get the number of arguments of a method invocation node.

This function also allow to identify whether a node is a method invocation node. If the input node is not a method invocation node, just return.

Parameters

[in]	MethodInvocationNode	Method invocation node.
[out]	IsMethodInvocation	Boolean stating whether the input node is a method invocation.
[out]	ArgCount	Number of arguments of the method invocation. Set to 0 if MethodInvocationNode is not a method invocation.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_BUFFER_TOO_SMALL	No space left in the buffer.
EFI_INVALID_PARAMETER	Invalid parameter.
EFI_OUT_OF_RESOURCES	Could not allocate memory.

Definition at line 1443 of file AmlMethodParser.c.

◆ AmlInitRawPathBStream()

STATIC EFI_STATUS EFIAPI AmlInitRawPathBStream	(	IN CONST AML_STREAM *	FStream,
		OUT AML_STREAM *	RawPathNameBStream
	)

From a forward stream pointing to a NameString, initialize a raw backward stream.

StartOfStream

Fstream: CurrPos EndOfStream v v +--------------------------------------—+ |^^^[Multi-name prefix]AAAA.BBBB.CCCC | +--------------------------------------—+ ^ ^ RawPathNameBStream: EndOfStream CurrPos StartOfStream

No memory is allocated when initializing the stream.

Parameters

[in]	FStream	Forward stream pointing to a NameString. The stream must not be at its end.
[out]	RawPathNameBStream	Backward stream containing the raw AML path.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 218 of file AmlMethodParser.c.

◆ AmlIsMethodInvocation()

EFI_STATUS EFIAPI AmlIsMethodInvocation	(	IN CONST AML_NODE_HEADER *	ParentNode,
		IN CONST AML_STREAM *	FStream,
		IN CONST LIST_ENTRY *	NameSpaceRefList,
		OUT AML_NAMESPACE_REF_NODE **	OutNameSpaceRefNode
	)

Check whether a pathname is a method invocation.

If there is a matching method definition, returns the corresponding NameSpaceRef node.

To do so, the NameSpaceRefList is keeping track of every namespace node and its raw AML absolute path. To check whether a pathname is a method invocation, a corresponding raw absolute pathname is built. This raw absolute pathname is then compared to the list of available pathnames. If a pathname defining a method matches the scope of the input pathname, return.

Parameters

[in]	ParentNode	Parent node. Node to which the node to be created will be attached.
[in]	FStream	Forward stream pointing to the NameString to find.
[in]	NameSpaceRefList	List of NameSpaceRef nodes.
[out]	OutNameSpaceRefNode	If the NameString pointed by FStream is a method invocation, OutNameSpaceRefNode contains the NameSpaceRef corresponding to the method definition. NULL otherwise.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 965 of file AmlMethodParser.c.

◆ AmlResolveAliasMethod()

STATIC EFI_STATUS EFIAPI AmlResolveAliasMethod	(	IN CONST AML_OBJECT_NODE *	AliasNode,
		IN CONST LIST_ENTRY *	NameSpaceRefList,
		OUT AML_NAMESPACE_REF_NODE **	OutNameSpaceRefNode
	)

Check whether an alias can be resolved to a method definition.

Indeed, the following ASL code must be handled: Method (MET0, 1) { Return (0x9) } Alias (\MET0, \ALI0) Alias (\ALI0, \ALI1) \ALI1(0x5) When searching for \ALI1 in the AML NameSpace, it resolves to \ALI0. When searching for \ALI0 in the AML NameSpace, it resolves to \MET0. When searching for \MET0 in the AML NameSpace, it resolves to a method definition.

This method is a wrapper to recursively call AmlFindMethodDefinition.

Parameters

[in]	AliasNode	Pointer to an Alias object node.
[in]	NameSpaceRefList	List of NameSpaceRef nodes.
[out]	OutNameSpaceRefNode	If success, and if the alias is resolved to a method definition (this can go through other alias indirections), containing the corresponding NameSpaceRef node.

Return values

EFI_SUCCESS	The function completed successfully.
EFI_INVALID_PARAMETER	Invalid parameter.

Definition at line 612 of file AmlMethodParser.c.

Functions

Detailed Description

Function Documentation

◆ AmlAddNameSpaceReference()

◆ AmlBuildRawMethodAbsolutePath()

◆ AmlCompareRawNameString()

◆ AmlCreateMethodInvocationNode()

◆ AmlCreateMethodRefNode()

◆ AmlDbgPrintNameSpaceRefList()

◆ AmlDeleteNameSpaceRefList()

◆ AmlDeleteNameSpaceRefNode()

◆ AmlFindMethodDefinition()

◆ AmlGetFirstNamedAncestorNode()

◆ AmlGetMethodInvocationArgCount()

◆ AmlInitRawPathBStream()

◆ AmlIsMethodInvocation()

◆ AmlResolveAliasMethod()