The DynamicPlatRepo library allows to handle dynamically created
CmObj. The dynamic platform repository can be in the following states:
1 - Non-initialised
2 - Transient:
Possibility to add CmObj to the platform, but not to query them.
3 - Finalised:
Possibility to query CmObj, but not to add new.
A token is allocated to each CmObj added to the dynamic platform
repository (except for reference tokens CmObj). This allows to retrieve
dynamic CmObjs among all CmObj (static CmObj for instance).
This patch add the TokenGenerator files.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Handle the EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_16550_WITH_GAS
id when generating an AML description of a serial port. The same
_HID/_CID as the EFI_ACPI_DBG2_PORT_SUBTYPE_SERIAL_FULL_16550
are generated.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Hardware information parser is an optional module defined
by the Dynamic Tables Framework. It can either parse an
XML, a Device Tree or a Json file containing the platform
hardware information to populate the platform information
repository.
FdtHwInfoParser library is an instance of a HwInfoParser
that parses a Device Tree and populates the Configuration
Manager Platform information repository.
FdtHwInfoParser library is aimed at providing a solution
for generating ACPI tables for Guest Partitions launched
by virtual machine managers (VMMs). One such use case is
Kvmtool where the Device Tree for the Guest is passed on
to the firmware by Kvmtool. The Configuration Manager for
Kvmtool firmware shall invoke the FdtHwInfoParser to parse
the Device Tree to populate the hardware information in
the Platform Info Repository. The Kvmtool Configuration
Manager can the process this information to generate the
required ACPI tables for the Guest VM.
This approach also scales well if the number of CPUs or
if the hardware configuration of the Guest partition is
varied.
FdtHwInfoParser thereby introduces 'Dynamic Tables for
Virtual Machines'.
Ref:https://bugzilla.tianocore.org/show_bug.cgi?id=3741
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
On platforms that implement PCIe, the PCIe configuration space
information must be described to a standards-based operating
system in the Memory mapped configuration space base address
Description (MCFG) table.
The PCIe information is described in the platform Device Tree,
the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/pci/
host-generic-pci.yaml
The FdtHwInfoParser implements a PCI configuration space Parser
that parses the platform Device Tree to create
CM_ARM_PCI_CONFIG_SPACE_INFO objects which are encapsulated in a
Configuration Manager descriptor object and added to the platform
information repository.
The platform Configuration Manager can then utilise this
information when generating the MCFG table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The GIC Dispatcher is the top-level component that is responsible
for invoking the respective parsers for GICC, GICD, GIC MSI Frame,
GIC ITS and the GICR.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The GIC Redistributor (GICR) structure is part of the Multiple
APIC Description Table (MADT) that enables the discovery of
GIC Redistributor base addresses by providing the Physical Base
Address of a page range containing the GIC Redistributors. More
than one GICR Structure may be presented in the MADT. The GICR
structures should only be used when describing GIC version 3 or
higher.
The GIC Redistributor information is described in the platform
Device Tree, the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic-v3.yaml
The FdtHwInfoParser implements a GIC Redistributor Parser that
parses the platform Device Tree to create CM_ARM_GIC_REDIST_INFO
objects which are encapsulated in a Configuration Manager
descriptor object and added to the platform information
repository.
The platform Configuration Manager can then utilise this
information when generating the MADT table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Arm GIC v3/v4 optionally includes support for GIC Interrupt
Translation Service (ITS). The GIC ITS Structure is part of
the Multiple APIC Description Table (MADT) that describes
the GIC Interrupt Translation service to the OS.
The GIC Interrupt Translation Service information is described
in the platform Device Tree, the bindings for which can be
found at:
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic-v3.yaml
The FdtHwInfoParser implements a GIC ITS Parser that parses the
platform Device Tree to create CM_ARM_GIC_ITS_INFO objects which
are encapsulated in a Configuration Manager descriptor object and
added to the platform information repository.
The platform Configuration Manager can then utilise this information
when generating the MADT table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Arm GIC version 2 systems that support Message Signalled Interrupts
implement GICv2m MSI frame(s). Each GICv2m MSI frame consists of a
4k page which includes registers to generate message signalled
interrupts to an associated GIC distributor. The frame also includes
registers to discover the set of distributor lines which may be
signalled by MSIs from that frame. A system may have multiple MSI
frames, and separate frames may be defined for secure and non-secure
access.
A MSI Frame structure is part of the Multiple APIC Description Table
(MADT) and must only be used to describe non-secure MSI frames.
The MSI Frame information is described in the platform Device Tree,
the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic.yaml
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic-v3.yaml
The FdtHwInfoParser implements a MSI Frame Parser that parses
the platform Device Tree to create CM_ARM_GIC_MSI_FRAME_INFO
objects which are encapsulated in a Configuration Manager
descriptor object and added to the platform information
repository.
The platform Configuration Manager can then utilise this
information when generating the MADT table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
On ARM-based systems the Generic Interrupt Controller (GIC)
manages interrupts on the system. Each interrupt is identified
in the GIC by an interrupt identifier (INTID). ACPI GSIVs map
one to one to GIC INTIDs for peripheral interrupts, whether
shared (SPI) or private (PPI). The GIC distributor provides
the routing configuration for the interrupts.
The GIC Distributor (GICD) structure is part of the Multiple
APIC Description Table (MADT) that describes the GIC
distributor to the OS. The MADT table is a mandatory table
required for booting a standards-based operating system.
The GIC Distributor information is described in the platform
Device Tree, the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic.yaml
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic-v3.yaml
The FdtHwInfoParser implements a GIC Distributor Parser that
parses the platform Device Tree to create CM_ARM_GICD_INFO
object which is encapsulated in a Configuration Manager
descriptor object and added to the platform information
repository.
The platform Configuration Manager can then utilise this
information when generating the MADT table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The GIC CPU Interface (GICC) structure is part of the Multiple
APIC Description Table (MADT) that describes the interrupt model
for the platform. The MADT table is a mandatory table required
for booting a standards-based operating system.
Arm requires the GIC interrupt model, in which the logical
processors are required to have a Processor Device object in
the DSDT, and must convey each processor's GIC information to
the OS using the GICC structure.
The CPU and GIC information is described in the platform Device
Tree, the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/arm/cpus.yaml
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic.yaml
- linux/Documentation/devicetree/bindings/interrupt-controller/
arm,gic-v3.yaml
The FdtHwInfoParser implements a GIC CPU Interface Parser that
parses the platform Device Tree to create CM_ARM_GICC_INFO
objects which are encapsulated in a Configuration Manager
descriptor object and added to the platform information
repository.
The platform Configuration Manager can then utilise this
information when generating the MADT and the SSDT CPU
information tables.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The Microsoft Debug Port Table 2 (DBG2), the Serial Port Console
Redirector (SPCR) table are mandatory tables required for booting
a standards-based operating system. The DBG2 table is used by the
OS debugger while the SPCR table is used to configure the serial
terminal. Additionally, the serial ports available on a platform
for generic use also need to be described in DSDT/SSDT for an OS
to be able to use the serial ports.
The Arm Base System Architecture 1.0 specification a lists of
supported serial port hardware for Arm Platforms. This list
includes the following serial port UARTs:
- SBSA/Generic UART
- a fully 16550 compatible UART.
Along, with these the PL011 UART is the most commonly used serial
port hardware on Arm platforms.
The serial port hardware information is described in the platform
Device Tree, the bindings for which can be found at:
- linux/Documentation/devicetree/bindings/serial/serial.yaml
- linux/Documentation/devicetree/bindings/serial/8250.txt
- linux/Documentation/devicetree/bindings/serial/arm_sbsa_uart.txt
- linux/Documentation/devicetree/bindings/serial/pl011.yaml
The FdtHwInfoParser implements a Serial Port Parser that parses
the platform Device Tree to create CM_ARM_SERIAL_PORT_INFO objects
with the following IDs:
- EArmObjSerialConsolePortInfo (for use by SPCR)
- EArmObjSerialDebugPortInfo (for use by DBG2)
- EArmObjSerialPortInfo (for use as generic Serial Ports)
The Serial Port for use by SPCR is selected by parsing the Device
Tree for the '/chosen' node with the 'stdout-path' property. The
next Serial Port is selected for use as the Debug Serial Port and
the remaining serial ports are used as generic serial ports.
The CM_ARM_SERIAL_PORT_INFO objects are encapsulated in Configuration
Manager descriptor objects with the respective IDs and are added to
the platform information repository.
The platform Configuration Manager can then utilise this information
when generating the DBG2, SPCR and the SSDT serial port tables.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The Generic Timer Description Table (GTDT) is a mandatory table
required for booting a standards-based operating system. It
provides an OSPM with information about a system's Generic Timer
configuration. The Generic Timer (GT) is a standard timer interface
implemented on ARM processor-based systems. The GTDT provides OSPM
with information about a system's GT interrupt configurations, for
both per-processor timers, and platform (memory-mapped) timers.
The Generic Timer information is described in the platform Device
Tree. The Device Tree bindings for the Generic timers can be found
at:
- linux/Documentation/devicetree/bindings/timer/arm,arch_timer.yaml
The FdtHwInfoParser implements a Generic Timer Parser that parses
the platform Device Tree to create a CM_ARM_GENERIC_TIMER_INFO
object. The CM_ARM_GENERIC_TIMER_INFO object is encapsulated in a
Configuration Manager descriptor object and added to the platform
information repository.
The platform Configuration Manager can then utilise this information
when generating the GTDT table.
Note: The Generic Timer Parser currently does not support parsing
of memory-mapped platform timers.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The Fixed ACPI Description Table (FADT) is a mandatory table
required for booting a standards-based operating system. The
FADT table has an 'ARM Boot Architecture Flags' field that is
used by an OS at boot time to determine the code path during
boot. This field is used to specify if the platform complies
with the PSCI specification. It is also used to describe the
conduit (SMC/HVC) to be used for PSCI.
The PSCI compliance information for a platform is described
in the platform Device Tree, the bindings for which can be
found at:
- linux/Documentation/devicetree/bindings/arm/psci.yaml
The FdtHwInfoParser implements a Boot Arch Parser that parses
the platform Device Tree to create a CM_ARM_BOOT_ARCH_INFO
object. The CM_ARM_BOOT_ARCH_INFO object is encapsulated in
a Configuration Manager descriptor object and added to the
platform information repository.
The platform Configuration Manager can then utilise this
information when generating the FADT table.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The FdtHwInfoParser parses a platform Device Tree and populates
the Platform Information repository with Configuration Manager
objects.
Therefore, add a set of helper functions to simplify parsing of
the platform Device Tree.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
FdtHwInfoParserLib is an instance of the HwInfoParser. The
FdtHwInfoParser parses a platform Device Tree and populates
the Platform Information repository with Configuration
Manager objects that describe the platform hardware.
These Configuration Manager objects are encapsulated in
Configuration Manager Object Descriptors.
Therefore, add helper functions to create and free the
Configuration Manager Object descriptors.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
When a CmObjDesc contains multiple objects, only the first one is
parsed as the buffer doesn't progress. Fix this.
Also check that the whole buffer has been parsed with an asset.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
This generator allows to generate a SSDT table describing
a Pci express Bus. It uses the following CmObj:
- EArmObjCmRef
- EArmObjPciConfigSpaceInfo
- EArmObjPciAddressMapInfo
- EArmObjPciInterruptMapInfo
REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3682
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Introduce the following CmObj in the ArmNameSpaceObjects:
- CM_ARM_PCI_ADDRESS_MAP_INFO
- CM_ARM_PCI_INTERRUPT_MAP_INFO
These objects allow to describe address range mapping
of Pci busses and interrupt mapping of Pci devices.
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
This function allows to add a node as the last node of a parent node
in an AML tree. For instance,
ASL code corresponding to NewNode:
Name (_UID, 0)
ASL code corresponding to ParentNode:
Device (PCI0) {
Name(_HID, EISAID("PNP0A08"))
}
"AmlAttachNode (ParentNode, NewNode)" will result in:
ASL code:
Device (PCI0) {
Name(_HID, EISAID("PNP0A08"))
Name (_UID, 0)
}
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
_PRT entries can describe interrupt mapping for Pci devices. The
object is described in ACPI 6.4 s6.2.13 "_PRT (PCI Routing Table)".
Add AmlCodeGenPrtEntry() helper function to add _PRT entries
to an existing _PRT object.
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Add AmlCodeGenNameResourceTemplate() to generate code for a
ResourceTemplate().
AmlCodeGenNameResourceTemplate ("REST", ParentNode, NewObjectNode) is
equivalent of the following ASL code:
Name(REST, ResourceTemplate () {})
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Add AmlCodeGenNamePackage() to generate code for a Package().
AmlCodeGenNamePackage ("PACK", ParentNode, NewObjectNode) is
equivalent of the following ASL code:
Name(PACK, Package () {})
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Add helper functions to generate AML Resource Data describing memory
ranges. Memory ranges can be one, double or four words long. They
can be of 'normal', IO or bus number memory type. The following
APIs are exposed:
- AmlCodeGenRdDWordIo ()
- AmlCodeGenRdDWordMemory ()
- AmlCodeGenRdWordBusNumber ()
- AmlCodeGenRdQWordMemory ()
To: Sami Mujawar <sami.mujawar@arm.com>
To: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Bugzilla: 3697 (https://bugzilla.tianocore.org/show_bug.cgi?id=3697)
Update the PPTT generator with the CacheId field as defined in table
5.140 of the ACPI 6.4 specification.
Also add validations to ensure that the cache id generated is unique.
Signed-off-by: Chris Jones <christopher.jones@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Bugzilla: 3697 (https://bugzilla.tianocore.org/show_bug.cgi?id=3697)
Update the PPTT generator to use Acpi64.h.
Signed-off-by: Chris Jones <christopher.jones@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Bugzilla: 3697 (https://bugzilla.tianocore.org/show_bug.cgi?id=3697)
ACPI 6.3A deprecated PPTT ID (type 2) structure which was subsequently
removed in ACPI 6.4. Therefore remove support for generating PPTT ID
structures.
Mantis ID for removing PPTT type 2 structure:
2072 (https://mantis.uefi.org/mantis/view.php?id=2072)
Signed-off-by: Chris Jones <christopher.jones@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
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>
REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3767
Update use of DEBUG_CODE(Expression) if Expression is a complex code
block with if/while/for/case statements that use {}.
Cc: Andrew Fish <afish@apple.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael Kubacki <michael.kubacki@microsoft.com>
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
REF: https://bugzilla.tianocore.org/show_bug.cgi?id=3760
Update all use of ', OPTIONAL' to ' OPTIONAL,' for function params.
Cc: Andrew Fish <afish@apple.com>
Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Michael Kubacki <michael.kubacki@microsoft.com>
Signed-off-by: Michael D Kinney <michael.d.kinney@intel.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Building the DynamicTablesPkg with the additional
-Wpointer-arith flag triggers the following error:
"pointer of type ‘void *’ used in arithmetic
[-Werror=pointer-arith]"
Cast the void pointer to fix the error.
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
In the success case we should return EFI_SUCCESS rather than returning
a potentially unitialized value of Status.
Cc: Sami Mujawar <Sami.Mujawar@arm.com>
Cc: Alexei Fedorov <Alexei.Fedorov@arm.com>
Signed-off-by: Moritz Fischer <moritzf@google.com>
In the GIC interrupt model, logical processors are required to
have a Processor Device object in the DSDT and must convey each
processor's GIC information to the OS using the GICC structure.
Additionally, _LPI objects may be needed as they provide a method
to describe Low Power Idle states that defines the local power
states for each node in a hierarchical processor topology.
Therefore, add support to generate the CPU topology and the LPI
state information in an SSDT table.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Introduce the CM_ARM_LPI_INFO CmObj in the ArmNameSpaceObjects.
This allows to describe LPI state information, as described in
ACPI 6.4, s8.4.4.3 "_LPI (Low Power Idle States)".
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlAddLpiState() to generates AML code to add an _LPI state
to an _LPI object created using AmlCreateLpiNode().
AmlAddLpiState increments the count of LPI states in the LPI
node by one, and adds the following package:
Package() {
MinResidency,
WorstCaseWakeLatency,
Flags,
ArchFlags,
ResCntFreq,
EnableParentState,
(GenericRegisterDescriptor != NULL) ? // Entry method. If a
ResourceTemplate(GenericRegisterDescriptor) : // Register is given,
Integer, // use it. Use the
// Integer otherwise
ResourceTemplate() { // NULL Residency
Register (SystemMemory, 0, 0, 0, 0) // Counter
},
ResourceTemplate() { // NULL Usage Counter
Register (SystemMemory, 0, 0, 0, 0)
},
"" // NULL State Name
},
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
_LPI object provides a method to describe Low Power Idle
states that define the local power states for each node
in a hierarchical processor topology.
Therefore, add AmlCreateLpiNode() to generate code for a
_LPI object.
AmlCreateLpiNode ("_LPI", 0, 1, ParentNode, &LpiNode) is
equivalent of the following ASL code:
Name (_LPI, Package (
0, // Revision
1, // LevelId
0 // Count
))
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlCodeGenMethodRetNameString() to generate AML code to create
a Method returning a NameString (NS).
AmlCodeGenMethodRetNameString (
"MET0", "_CRS", 1, TRUE, 3, ParentNode, NewObjectNode
);
is equivalent of the following ASL code:
Method(MET0, 1, Serialized, 3) {
Return (_CRS)
}
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlCodeGenReturnNameString() to generate AML code for a
Return object node, returning the object as a NameString.
AmlCodeGenReturn ("NAM1", ParentNode, NewObjectNode) is
equivalent of the following ASL code:
Return(NAM1)
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlCodeGenMethod() to generate code for a control method.
AmlCodeGenMethod ("MET0", 1, TRUE, 3, ParentNode, NewObjectNode)
is equivalent of the following ASL code:
Method(MET0, 1, Serialized, 3) {}
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
ASL provides a ResourceTemplate macro that creates a Buffer in which
resource descriptor macros can be listed. The ResourceTemplate macro
automatically generates an End descriptor and calculates the checksum
for the resource template.
Therefore, add AmlCodeGenResourceTemplate() to generate AML code for
the ResourceTemplate() macro. This function generates a Buffer node
with an EndTag resource data descriptor, which is similar to the ASL
ResourceTemplate() macro.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Some AML object have a PkgLen which indicates the size of the
AML object. The package length can be encoded in 1 to 4 bytes.
The bytes used to encode the PkgLen is itself counted in the
PkgLen value. So, if an AML object's size increments/decrements,
the number of bytes used to encode the PkgLen value can itself
increment/decrement.
Therefore, a helper function AmlComputePkgLength() is introduced
to simply computation of the PkgLen.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlCodeGenPackage() to generate AML code for declaring
a Package() object. This function generates an empty package
node. New elements can then be added to the package's variable
argument list.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add a helper function AmlCodeGenEndTag() to generate AML Resource Data
EndTag. The EndTag resource data is automatically generated by the ASL
compiler at the end of a list of resource data elements. Therefore, an
equivalent function is not present in ASL.
However, AmlCodeGenEndTag() is useful when generating AML code for the
ResourceTemplate() macro.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlCodeGenRegister() to generate AML code for the
Generic Register Resource Descriptor. This function is
equivalent to the ASL macro Register().
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Remove the STATIC qualifier for the AmlUtility function
AmlNodeGetIntegerValue() and add the definition to the
header file so that it can be used by other AmlLib
sub-modules.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The node creation functions:
- AmlCreateRootNode()
- AmlCreateObjectNode()
- AmlCreateDataNode()
are now resetting the input pointer where the created node is stored.
Thus, it is not necessary to set some local variables to NULL or
check a node value before trying to delete it.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The following functions:
- AmlCreateRootNode()
- AmlCreateObjectNode()
- AmlCreateDataNode()
create a node and return it by populating a pointer. This pointer
should only be considered/used if the function returns successfully.
Otherwise, the value stored in this pointer should be ignored.
For their error handling, some other functions assume that this
pointer is reset to NULL if an error occurs during a node creation.
To make this assumption correct, explicitly clear this input pointer.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
ACPI 6.4, s6.4.2.9 "End Tag":
"This checksum is generated such that adding it to the sum of all the data
bytes will produce a zero sum."
"If the checksum field is zero, the resource data is treated as if the
checksum operation succeeded. Configuration proceeds normally."
To avoid re-computing checksums, if a new resource data elements is
added/removed/modified in a list of resource data elements, the AmlLib
resets the checksum to 0.
This patch also refactors the AmlAppendRdNode() function by getting the
last Resource Data node directly instead of iterating over all the
elements of the list of Resource Data node.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Lists of Resource Data elements end with an EndTag (most of the time).
This function finds the EndTag (if present) in a list of Resource Data
elements and sets the checksum.
ACPI 6.4, s6.4.2.9 "End Tag":
"This checksum is generated such that adding it to the sum of all the data
bytes will produce a zero sum."
"If the checksum field is zero, the resource data is treated as if the
checksum operation succeeded. Configuration proceeds normally."
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add AmlRdSetEndTagChecksum(), setting the CheckSum value contained in a
Resource Data element.
ACPI 6.4, s6.4.2.9 "End Tag":
"This checksum is generated such that adding it to the sum of all the
data bytes will produce a zero sum."
"If the checksum field is zero, the resource data is treated as if the
checksum operation succeeded. Configuration proceeds normally."
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
To fetch the Oem information from the ConfigurationManagerProtocol
and the AcpiTableInfo, and populate the SSDT ACPI header when
creating a RootNode via the AmlLib, create AddSsdtAcpiHeader().
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add missing check of 'AcpiTableInfo' in AddAcpiHeader().
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Buzilla: 3565 (https://bugzilla.tianocore.org/show_bug.cgi?id=3565)
As part of the updates to ACPI 6.4 the "SBSA Generic Watchdog" was
renamed to the "Arm Generic Watchdog". This patch implements that
change by updating the GTDT generator to use Acpi64.h and renames
any occurence of "SBSA Generic Watchdog" to "Arm Generic Watchdog".
Signed-off-by: Chris Jones <christopher.jones@arm.com>
Reviewed-by: Zhichao Gao <zhichao.gao@intel.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Rework all the functions to to have a generic prototype:
- First take take the resource data specific arguments.
E.g.: for a Register(): the AddressSpace, BitWidth, ...
- The penultimate parameter is a NameOpNode. The resource data
created is appended to the ResourceTemplate() contained in the
NameOpNode.
- The last parameter is a pointer holding the created resource data.
A least one of the two last parameter must be provided. One of them can
be omitted. This generic interface allows to either:
- Add the resource data to a NameOpNode. This is a common case for the
Ssdt tables generator.
- Get the created resource data and let the caller place it in an AML
tree.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Some functions in the AmlLib have 'Crs' in their name and can only
be applied to '_CRS' AML objects. To re-use them on AML objects that
have different names:
- Rename them and remove the '_CRS' name check.
- Create aliases having of the 'Crs' function prototypes. These
aliases are available when DISABLE_NEW_DEPRECATED_INTERFACES
is not defined. They will be deprecated in a near future.
The deprecated functions are:
- AmlNameOpCrsGetFirstRdNode()
- AmlNameOpCrsGetNextRdNode()
- AmlCodeGenCrsAddRdInterrupt()
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The correct formatter to print a CHAR8 char in edk2 is '%a'.
Replace the '%s' formatters by '%a'.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The Platform information repository in the Configuration Manager
may be dynamically populated, for e.g. by a Hardware Information
Parser like FdtHwInfoParser. In such cases it is useful to trace
the CM objects that were populated by the parser.
Therefore, introduce helper functions that can parse and trace
the Configuration Manager Objects.
Reviewed-by: Joey Gouly <joey.gouly@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add a function converting a 7 characters string to its UINT32
EISAID. The algorithm used to create the EISAID is described
in the ACPI 6.4 specification, s19.3.4 "ASL Macros".
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Add HexFromAscii(), converting an hexadecimal ascii char
to an integer.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The Ecc tool forbids the usage of one char variable: Ecc error 8007:
"There should be no use of short (single character) variable names"
To follow this policy, rename this one letter parameter.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Update the inf file version and BASE_NAME of the library.
Remove unused sections.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
The TableHelperLib contains helper functions. Some rely on
DynamicTablesPkg definitions (they use Configuration Manager objects).
Some others are more generic.
To allow using these generic functions without including
DynamicTablesPkg definitions, move them to a new AcpiHelperLib
library.
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Use the newly introduced defined value in:
MdePkg/Include/IndustryStandard/AcpiAml.h
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Star Zeng <star.zeng@intel.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The DBG2 table generator set the access size for the UART to
DWORD (4 bytes) by default. However, according to Section B
Generic UART, Arm Base System Architecture 1.0, Platform
Design Document, a Generic UART can have BYTE, WORD or DWORD
access sizes. To address this an AccessSize field has been
introduced in CM_ARM_SERIAL_PORT_INFO object.
This patch updates the DBG2 generator to setup the AccessSize
field in the Generic Address Structure (GAS) for the UART in
the DBG2 table with information provided by the platform.
Signed-off-by: Joey Gouly <joey.gouly@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The SPCR table generator set the access size for the UART to
DWORD (4 bytes) by default. However, according to Section B
Generic UART, Arm Base System Architecture 1.0, Platform
Design Document, a Generic UART can have BYTE, WORD or DWORD
access sizes. To address this an AccessSize field has been
introduced in CM_ARM_SERIAL_PORT_INFO object.
This patch updates the SPCR generator to setup the AccessSize
field in the Generic Address Structure (GAS) for the UART in
the SPCR table with information provided by the platform.
Signed-off-by: Joey Gouly <joey.gouly@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
According to ACPI 6.4, 6.1.5 _HID states:
- A valid PNP ID must be of the form "AAA####" where A is an uppercase
letter and # is a hex digit.
- A valid ACPI ID must be of the form "NNNN####" where N is an uppercase
letter or a digit ('0'-'9') and # is a hex digit.
Signed-off-by: Joey Gouly <joey.gouly@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Building the DynamicTablesPkg for a NOOPT target
fails because unused variables are set.
Remove these variables.
Fixes: d9800046ea
Reported-by: Leif Lindholm <leif@nuviainc.com>
Signed-off-by: Pierre Gondois <Pierre.Gondois@arm.com>
Reviewed-by: Leif Lindholm <leif@nuviainc.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
Some platforms advertise support for a 16550 UART, but are not
compatible with the PNP0500 HID. Allow them to override the HID by
setting PcdNonBsaCompliant16550SerialHid.
Signed-off-by: Joey Gouly <joey.gouly@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Reviewed-by: Sami Mujawar <sami.mujawar@arm.com>
The Generic ACPI for Arm Components 1.0 Platform Design
Document, s2.6.4 "ASL code examples" provides information
to describe an Arm CoreLink CMN-600 Coherent Mesh Network
using an ASL definition block table.
The SSDT CMN-600 Table Generator uses the Configuration
Manager protocol to obtain the following information about
the CMN-600 device on the platform:
- the PERIPHBASE address location and address range;
- the ROOTNODEBASE address location;
- the number of Debug and Trace Controller (DTC)
and their respective interrupt number;
The CMN-600 mesh is described using the CM_ARM_CMN_600_INFO
and CM_ARM_EXTENDED_INTERRUPT structures in the Configuration
Manager.
The SSDT CMN-600 Table generator:
- gets the CMN-600 hardware information
from the configuration manager.
- uses the AmlLib interfaces to parse the AML
template BLOB and construct an AML tree.
- uses the AmlLib to update:
- the "_UID" value;
- the address location and range of the PERIPHBASE;
- the address location of the ROOTNODEBASE;
- the number of Debug and Trace Controller (DTC)
and their respective interrupt number;
- serializes the AML tree to an output buffer.
This output buffer contains the fixed-up AML code,
which is then installed as an ACPI SSDT table.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Co-authored-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Fix the following ECC reported errors in SsdtSerialPortFixupLib.
- [9002] The function headers should follow Doxygen special
documentation blocks in section 2.3.5 in Comment,
<@param [in]> does NOT have [in, out]
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Change the AML_DEBUG_STR() macro to AML_OPCODE_DEF() that takes a string
and the AML OpCode as input so that the text description and the AML
OpCode are grouped. The AML_OPCODE_DEF() macro also strips the string
description for release builds.
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@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>
Fix the following ECC reported error in AcpiSratLibArm.
- [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>
Fix the following ECC reported error in SsdtSerialPortLibArm.
- [5007] There should be no initialization of a variable as part of
its declaration Variable Name.
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Reordered the asserts to first check if the pointer is valid
before de-referencing the pointer.
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
The SSDT Serial port fixup library provides
interfaces to generate a SSDT Serial port table
based on the serial port information.
Update the DBG2 Generator to use the SSDT serial
port fixup library to build a serial port definition
block for the DBG2 serial port and install the
SSDT 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>
According to Arm Server Base Boot Requirements,
Platform Design Document version 1.2 revision D,
September 2, 2019, section '4.2.1.8 SPCR'; the
SPCR console device must be included in the DSDT.
The SSDT Serial port fixup library provides
interfaces to generate a SSDT Serial port table
based on the serial port information.
Update the SPCR Generator to use the SSDT serial
port fixup library to build a serial port definition
block corresponding to the SPCR serial port and
install the SSDT 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>
Most platforms have several serial ports. These serial ports
are described to an operating system using definition block
tables.
The SSDT Serial Port Table Generator uses the Configuration
Manager protocol to obtain information for the Serial Ports
on the platform. The serial ports are described using the
CM_ARM_SERIAL_PORT_INFO structure. The EArmObjSerialPortInfo
ID is used to represent a standard serial port.
The SSDT Serial port fixup library provides interfaces to
generate a SSDT Serial port table based on the serial port
information. The SSDT Serial Port Table Generator uses the
SSDT serial port fixup library to build serial port
definition blocks and installs the SSDT tables.
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>
According to Arm Server Base Boot Requirements,
Platform Design Document version 1.2 revision D,
September 2, 2019, section '4.2.1.8 SPCR'; The
SPCR console device must be included in the DSDT.
Additionally, it is often desirable to describe the
serial ports available on a platform so that they
are available for use by a rich OS.
To facilitate the description of serial ports on a
platform a common SSDT Serial Port Fixup library is
introduced. It provides interfaces to build a SSDT
serial port definition block table based on the
serial port information.
The SSDT Serial Port Fixup library is used by the
SPCR, DBG2 and SSDT Serial Port generator to describe
the serial port information in a definition block.
+------------+ +------------+ +------------+
| SPCR Gen | | DBG2 Gen | | SERIAL Gen |
+------------+ +------------+ +------------+
+----------------------------------+
| SSDT Serial Port Fixup library |
+----------------------------------+
The SSDT Serial Port Fixup library:
- Parses the SSDT Serial Port template using the
AmlLib library to generate an AML tree.
- Updates the _UID, _HID and _CID values.
- Fixes up the Serial port base address, length
and the interrupt number in the _CRS descriptor.
- Fixes up the serial-port name.
- Serialises the AML Tree to a buffer containing
the definition block data.
The definition block data is then installed by the
corresponding table generator.
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>
AsciiFromHex is a function converts a hex number to an
ASCII character. This function is used across multiple
generators, so add it to the TableHelperLib.
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>
ACPI Definition blocks are implemented using AML which has
a complex grammar making run-time generation of definition
blocks difficult. Dynamic AML is a feature of Dynamic Tables
framework that provides a solution for dynamic generation of
ACPI Definition block tables.
Since, AML bytecode represents complex AML grammar, an AmlLib
library is introduced to assist parsing and traversing of the
AML bytecode at run-time.
The AmlLib library parses a definition block and represents it
as an AML tree. The AML objects, methods and data are represented
as tree nodes. Since the AML data is represented as tree nodes,
it is possible to traverse the tree, locate a node and modify the
node data. The tree can then be serialized to a buffer (that
represents the definition block). This definition block containing
the fixed-up AML code can then be installed as an ACPI Definition
Block table.
Dynamic AML introduces the following techniques:
* AML Fixup
* AML Codegen
* AML Fixup + Codegen
AML Fixup is a technique that involves compiling an ASL template
file to generate AML bytecode. This template AML bytecode can be
parsed at run-time and a fixup code can update the required fields
in the AML template.
AML Codegen employs generating small segments of AML code.
AmlLib provides a rich set of APIs to operate on AML data for AML
Fixup and Codegen.
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>
AmlLib library implements an AML parser, AML tree interface,
serialiser, code generator and other interfaces to generate
Definition Block tables.
The AmlLib APIs are a collection of interfaces that enable
parsing, iterating, modifying, adding, and serialising AML
data to generate a Definition Block table.
The AmlLib APIs are declared in Include\AmlLib\AmlLib.h
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>
AML Core interface APIs are internal APIs of the
AmlLib library. These APIs can be used to:
- Create/Delete/Clone an AML tree/node
- Get/update Fixed and Variable arguments
- Serialize an AML tree.
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>
AML Codegen is a Dynamic AML technique that facilitates
generation of small segments of AML code. The AML code
generated using AML Codegen is represented as nodes in
the AML Tree.
AML Resource Data Codegen implements interfaces required
for generating Resource Data elements that can be attached
to an AML tree.
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>
AML Codegen is a Dynamic AML technique that facilitates
generation of small segments of AML code. The AML code
generated using AML Codegen is represented as nodes in
the AML Tree.
Some examples where AML Codegen can be used are:
- AML Codegen APIs can be used to generate a simple
AML tree.
- An AML template can be parsed to create an AML
tree. This AML Tree can be searched to locate a
node that needs updating. The AML Codegen APIs
can be used to attach new AML nodes.
- A combination of AML Fixup and AML Codegen can
be used to generate an AML tree.
The AML tree can then be serialised as a Definition
Block table.
Following AML Codegen APIs are implemented:
- AmlCodeGenDefinitionBlock()
- AmlCodeGenScope()
- AmlCodeGenNameString()
- AmlCodeGenNameInteger()
- AmlCodeGenDevice()
These AML Codegen APIs in combination with AML Resource
Data Codegen APIs can be used to generate a simple AML
tree.
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 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>
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. To simplify
operations on resource data, the resource data parser
examines the Bytelist to detect the presence of resource
data. If the data matches the encoding of resource
data type(s), the parser fragments the resource data
buffer into resource data elements (data nodes) and
stores them in the variable arguments list of the
BufferOp node.
The resource data helper provides functions and macros
to assist operations on resource data elements.
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>
AML is a declarative language that is processed by the
ACPI AML interpreter. The ACPI AML interpreter will
compile the set of declarations into the ACPI Namespace
at definition block load time.
The hardware information described in AML is effectively
mapped in the ACPI Namespace. The AML ACPI namespace
interface implement the functionality to search the ACPI
Namespace. Example: The AmlFindNode() can be used to locate
a device node in the ACPI namespace using an ASL path as
the search input.
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 debug print functions enable logging
of the operations on the AML tree and the data
output. The debug logging functionality is
enabled for debug builds when the DEBUG_INFO
or DEBUG_VERBOSE mask is enabled in the PCD
gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel
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>
AML Fixup and AML Codegen facilitate dynamic generation
of Definition Block tables. The AML byte stream that is
generated is represented in an AML tree. Once the AML
table generation is completed, the AML tree needs to be
serialised for installing as an ACPI table.
The AML serialise interface implements the functionality
to iterate the nodes in the AML tree, collating the AML
bytecode, computing the checksum and writing the AML byte
stream to a buffer that represents the Definition Block
table.
Signed-off-by: Pierre Gondois <pierre.gondois@arm.com>
Co-authored-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Dynamic AML involves parsing/packing of AML opcode and
data into AML byte streams. The AML stream interface
provides safe buffer management as well as supports
forward and reverse streams. It provides functions to
create, read, write, clone and compare AML streams.
Co-authored-by: Pierre Gondois <pierre.gondois@arm.com>
Signed-off-by: Sami Mujawar <sami.mujawar@arm.com>
Reviewed-by: Alexei Fedorov <Alexei.Fedorov@arm.com>
Dynamic AML requires encoding/decoding and conversion of
AML and ASL strings. A collection of helper functions
have been provided for internal use in the AmlLib Library.
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 utility interfaces are a collection of helper functions
that assist in computing the checksum, size and to propagate the
node information as a result of addition or update of AML nodes.
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>
It is often desirable to clone an AML branch/tree
or an AML node. An example of could be to clone
an AML template before fixup so that the original
AML template remains unmodified. Another example
would be replicating a device branch in the AML
tree and fixing up the device information.
To facilitate such scenarios the AmlLib library
provides functions that can be used to clone an
AML branch/tree or an AML node.
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 tree iterator provides interfaces to traverse the nodes
in the AML tree. The iterator can traverse the AML tree nodes in
the following order:
- Linear progression: Iterate following the AML byte stream
order (depth first).
- Branch progression: Iterate following the AML byte stream
order (depth first), but stop iterating
at the end of the branch.
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>
Pierre Gondois
Chris Jones
Michael Kubacki
Michael D Kinney
Moritz Fischer
Sami Mujawar
Joey Gouly