Features

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:

{
    "_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"
    ]
}

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 model

Parameters

The 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.

Constraints

In the example above you see the following concepts expressed:

• Four definitions of boolean parameters are made, where:
  • v8Ap1 and v8Ap2 are architecture extensions.
  • FEAT_A and FEAT_B are features.
• The v8Ap2 parameter has a constraint (which is defined globally) expressed as v8Ap2 ==> v8Ap1, which signifies that v8Ap2 architecture extension is v8Ap1 compliant. Formally:
  • When v8Ap2 is set to true ('implemented' in architectural terms) then v8Ap1 must be true (implemented).
  • When v8Ap1 is false then v8Ap2 cannot be true.
  • When v8Ap1 is true, no assumption can be made about v8Ap2.
• The 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:
    • If FEAT_A is true then the value of AArch64-IDREG.A is >= 1.
    • If the value of AArch64-IDREG.A is '0001' then FEAT_A must be true.
• The FEAT_B parameter has the following constraints:
  • v8Ap2 ==> FEAT_B : FEAT_B is mandatory from Armv8.2
  • Mandatory features are usually permitted in an earlier version FEAT_B ==> v8Ap1 : FEAT_B is OPTIONAL from Armv8.1.
  • Features sometimes require other features to be implemented. FEAT_B ==> FEAT_A : If FEAT_B is implemented, then FEAT_A is implemented.
• In 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.
• In 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.