The Features model stores information about the architectural configuration
using constraints, where constraints can be relationships between multiple features (FEAT_X
),
multiple architectural versions (v8Ap1
) and register ID fields.
For example, see below for a Features file that tries to express all these relationships:
Note
In this documentation for ease, we write constraints as strings A --> B
. However,
in the data, this is stored as AST.BinaryOp.
{
"_type": "Features",
"parameters": [
{
"_type": "Parameters.Boolean",
"name": "v8Ap1",
"title": "v8.1 A-Profile"
},
{
"_type": "Parameters.Boolean",
"name": "v8Ap2",
"title": "v8.2 A-Profile"
},
{
"_type": "Parameters.Boolean",
"name": "FEAT_A",
"title": "Feature A",
"constraints": [
"FEAT_A --> v8Ap2",
"FEAT_A <-> UInt(AArch64-IDREG.A) >= 1"
]
},
{
"_type": "Parameters.Boolean",
"name": "FEAT_B",
"title": "Feature B",
"constraints": [
"v8Ap2 --> FEAT_B",
"FEAT_B --> v8Ap1",
"FEAT_B --> FEAT_A"
]
},
{
"_type": "Parameters.Integer",
"name": "NUM_COUNTERS",
"title": "Number of Counters",
"values": [
0,
1,
2,
3
],
"constraints": [
"NUM_COUNTERS == UInt(AArch64-IDREG.Counters)"
]
},
{
"_type": "Parameters.Integer",
"name": "DEBUG_LEVEL",
"title": "Debugger verbosity Level",
"values": [
0,
1,
2
],
"constraints": [
"DEBUG_LEVEL == UInt(Configuration.Debugger.Verbosity)"
]
}
],
"constraints": [
"v8Ap2 --> v8Ap1"
]
}
Note
The Features model does not make any differentiation between an architecture version or a
feature. They are all represented as Parameters.*
, and boolean logic connects them
together using <->
(if-and-only-if) and -->
(if-then).
The Features model holds two main keys:
parameters
: A list of all named Parameters types.
For detail around all types of supported parameters.constraints
: A list of constraints specified in ASL, shown here as string but stored as an AST
in the data modelThe parameters
property provides a list of Parameters types, where each parameter contains:
_type
, which defines the type of the parameter,name
, a unique name associated with this parameter. All names (irrelevant of their types) must
be unique.title
, a human-readable title for the feature.values
, the allowed domain of the current parameter.description
(not shown), a human-readable descriptive content.See Parameters for more detail around each property above and different types of parameters.
Note
In the example above, the constraint
property can be found attached to a Parameter
or attached to the top Features
level. This is done as an aid to help users
define constraints closer to the context. However the system does not make any distinction
and treats all constraints globally.
In the example above you see the following concepts expressed:
v8Ap1
and v8Ap2
are architecture extensions.FEAT_A
and FEAT_B
are features.v8Ap2
parameter has a constraint (which is defined globally) expressed as v8Ap2 --> v8Ap1
,
which signifies that v8Ap2
architecture extension is v8Ap1
compliant. Formally:v8Ap2
is set to true
('implemented' in architectural terms) then v8Ap1
must be
true
(implemented).v8Ap1
is false
then v8Ap2
cannot be true
.v8Ap1
is true
, no assumption can be made about v8Ap2
.FEAT_A
parameter has the following constraints:FEAT_A --> v8Ap2
which is equivalent to FEAT_A is OPTIONAL from Armv8.2
.FEAT_A <-> UInt(AArch64-IDREG.A) >= 1'
which is FEAT_A is implemented if and only if IDREG.A holds a value >= 1
. This means that:FEAT_A
is true then the value of AArch64-IDREG.A
is >= 1
.AArch64-IDREG.A
is '0001'
then FEAT_A
must be true.FEAT_B
parameter has the following constraints:v8Ap2 --> FEAT_B
: FEAT_B is mandatory from Armv8.2
FEAT_B --> v8Ap1
: FEAT_B is OPTIONAL from Armv8.1
.FEAT_B --> FEAT_A
: If FEAT_B is implemented, then FEAT_A is implemented
.NUM_COUNTERS
we see an integer parameter that is equal to the AArch64-IDREG.Counters
Field.
Noting that the UInt
cast is important because in ASL AArch64-IDREG.Counters
is
represented as bits, and NUM_COUNTERS
is represented as an integer meaning that for
NUM_COUNTERS == UInt(AArch64-IDREG.Counters)
to work the domains on both sides should match.DEBUG_LEVEL
we see an integer parameter that is equal to the Configuration.Debugger.Verbosity
DotAtom.
This DotAtom refers to the "Verbosity" property of the "Debugger" object, which is accessed as a property of the "Configuration" object.
As with NUM_COUNTERS
above, the property is stored as bits and must be cast to UInt
for comparison.To understand complex relationships that can be expressed please see Traits.HasConstraints documentation.