REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3737
Apply uncrustify changes to .c/.h files in the DynamicTablesPkg package
Cc: Andrew Fish <afish@apple.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Signed-off-by: Michael Kubacki <michael.kubacki@microsoft.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Fix ECC error 8001 reported errors in AmlDbgPrint.
[8001] Only capital letters are allowed to be used
for #define declarations.
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Fix the following ECC reported errors in AmlLib.
- [1008] File has invalid Non-ACSII char.
- [9002] The function headers should follow Doxygen special
documentation blocks in section 2.3.5 Comment does NOT
have tail **/
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
The AML language allows defining field lists in a Definition
Block. Although Dynamic AML does not provide interfaces to
modify Field Lists; an AML template code may contain Field
lists and the AML parser must be capable of parsing and
representing the Field lists in the AML tree.
The AML parser creates an Object node that represents the
'Field Node'. The AML Field list parser creates an object
node for each field element parsed in the AML byte stream,
and adds them to the variable list of arguments of the
'Field Node'.
Nodes that can have a field list are referred as 'Field
nodes'. They have the AML_HAS_FIELD_LIST attribute set in
the AML encoding.
According to the ACPI 6.3 specification, s20.2.5.2 "Named
Objects Encoding", field elements can be:
- NamedField := NameSeg PkgLength;
- ReservedField := 0x00 PkgLength;
- AccessField := 0x01 AccessType AccessAttrib;
- ConnectField := <0x02 NameString> | <0x02 BufferData>;
- ExtendedAccessField := 0x03 AccessType ExtendedAccessAttrib
AccessLength.
A small set of opcodes describes the field elements. They are
referred as field opcodes. An AML_BYTE_ENCODING table has been
created for field OpCodes.
Field elements:
- don't have a SubOpCode;
- have at most 3 fixed arguments (as opposed to 6 for standard
AML objects);
- don't have a variable list of arguments;
- only the NamedField field element is part of the AML namespace.
ConnectField's BufferData is a buffer node containing a single
resource data element.
NamedField field elements do not have an AML OpCode. NameSeg
starts with a Char type and can thus be differentiated from the
Opcodes for other fields.
A pseudo OpCode has been created to simplify the parser.
Following is a representation of a field node in an AML tree:
(FieldNode)
\
|- [0][1][3] # Fixed Arguments
|- {(FldEl0)->(FldEl1)->...)} # Variable Arguments
Where FldEl[n] is one of NamedField, ReservedField, AccessField,
ConnectField, ExtendedAccessField.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
The AML language allows a Definition Block to implement
methods that an Operating System can invoke at runtime.
Although Dynamic AML does not provide interfaces to
modify AML methods; an AML template code may contain
methods and/or method invocations.
Method definitions have an opcode defined in the AML
encoding and can be easily parsed. However, the language
does not define an opcode for method invocation. Method
invocations are represented as a NameString followed by
the arguments to the method. This poses a significant
challenge for the AML parser as it has to determine if
a NameString appearing in the AML byte stream is a method
invocation and if it is a method invocation, then how
many arguments follow.
This also means the Method definition must occur prior to
the method invocation in the AML byte stream. This is a
hard requirement for the AML parser.
The AML method parser maintains a NameSpaceRefList that
keeps a track of every namespace node and its raw AML
absolute path. The AmlIsMethodInvocation() searches the
NameSpaceRefList to determine if a NameString matches
a Method definition.
A pseudo opcode has been defined in the AML encoding to
represent the Method invocation in the AML tree.
The AML encoding for method invocations in the ACPI
specification 6.3 is:
MethodInvocation := NameString TermArgList
The AmlLib library redefines this as:
MethodInvocation := MethodInvocationOp NameString
ArgumentCount TermArgList
ArgumentCount := ByteData
Where MethodInvocationOp is the pseudo opcode and
ArgumentCount is the number of arguments passed to
the method.
NOTE:
The AmlLib library's definition for a method
invocation only applies to the representation
of method invocation node in the AML tree.
When computing the size of a tree or serialising
it, the additional data is not taken into account
i.e. the MethodInvocationOp and the ArgumentCount
are stripped before serialising.
Method invocation nodes have the AML_METHOD_INVOVATION
attribute set in the AmlLib library's representation of
the AML encoding.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Resource data are defined in the ACPI 6.3 specification,
s6.4 "Resource Data Types for ACPI". They can be created
using the ASL ResourceTemplate () statement, cf s19.3.3
"ASL Resource Templates".
Resource data can be of the small or large type and are
defined by their encoding. The resource data is stored
in the Bytelist of a BufferOp node. The Bytelist of a
BufferOp node is represented by an AML Data node in
the AML tree.
The resource data parser, examines the Bytelist (Data
node buffer) to detect the presence of resource data.
If the Bytelist data matches the encoding for resource
data types, the resource data parser fragments the
Bytelist containing the resource data buffer into
resource data elements represented as individual Data
nodes and stores them in the variable arguments list
of the BufferOp object nodes.
Example: ASL code and the corresponding AML tree
representation for the resource data.
ASL Code
--------
Name (_CRS, ResourceTemplate() {
QWordMemory (...)
Interrupt (...)
}
AML Tree
--------
(NameOp)
\
|-[_CRS]-[BufferOp] # Fixed Arguments
|-{NULL} \ # Variable Argument
\ list
|-[BuffSize] # Fixed Arguments
|-{(Rd1)->(Rd2)->(EndTag)} # Variable Argument
list
Where:
Rd1 - QWordMemory resource data element.
Rd2 - Interrupt resource data element.
EndTag - Resource data end tag.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Both ASL and AML are declarative language. The ASL code
is compiled to AML bytecode. The AML bytecode is processed
by the ACPI AML interpreter that runs as part of an OS.
AML has a complex encoding making dynamic generation of
Definition Block tables difficult.
Dynamic AML generation involves techniques like AML Fixup
and AML Codegen, both requiring parsing of AML bytecode.
The AML parser is a module that parses an AML byte stream
and represents it as an AML tree. Representing the AML
bytecode as an AML tree is key to reducing the complexity
and enabling Dynamic AML generation.
In an AML Tree each AML statement (that also corresponds
to an ASL statement) is represented as an 'Object Node'.
Each Object Node has an OpCode and up to 6 Fixed Arguments
followed by a list of Variable Arguments.
(ObjectNode)
\
|- [0][1][2][3][4][5] # Fixed Arguments
|- {(VarArg1)->(VarArg2)->...N} # Variable Arguments
A Fixed Argument or Variable Argument can be either an
Object Node or a Data Node.
A 'Data Node' consists of a data buffer.
A 'Root Node' is a special type of Object Node that does
not have an Opcode or Fixed Arguments. It only has a list
of Variable Arguments. The Root Node is at the top of the
AML tree and contains the Definition Block Header.
The AML parser uses the 'AML Encoding' to parse an AML byte
stream and represents it as an AML Tree. Representing in the
form of an AML tree simplifies modification, addition and
removal of the tree nodes. The modified tree can then be
serialised to a buffer representing a Definition Block table.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Michael Kubacki
Sami Mujawar
Pierre Gondois