Device Tree Validation#

The Device Tree Validation tool validates device tree configurations against configuration specifications, helping identify errors before flashing to the target. For details on the specification format and field definitions, see Configuration Specification.

The tool supports two validation modes:

  • DTB validation – Validates property values in a DTB against the upstream specification. This checks data types, value ranges, allowed enums, and other structural constraints.

  • Annotated DTS validation – Checks customer configurability using annotated DTS files. Ensures that customer-configurable properties in the final DTB originate from driveos_customer_config, and that non-customer-configurable properties do not.

Validation During Build#

To run validation as part of the build, pass the ENABLE_DT_VALIDATION=y flag to bind_partitions:

For example:

bind_partitions -b p3960-10-sw03 linux ENABLE_DT_VALIDATION=y

Validation runs after the DTB is generated and produces a validation log in the build output directory. Refer to Bind Partitions for details on the bind_partitions command.

Standalone Validation#

Validation can also be run independently from bind_partitions. This involves three steps:

  1. Environment Setup: Configure paths to the validation tools.

  2. Generate Schema: Combine input specification files into a single schema file. This is a one-time step; the generated schema can be reused across multiple validation runs.

  3. Validate: Validate DTBs or annotated DTS files against the generated schema.

Environment Setup#

Set the following environment variables to point to the validation tools:

export PYTHONPATH=$SDK_TOP/tools/pct/schema_validation/devicetree-validation/dtschema_bin:${PYTHONPATH}
export PATH=$SDK_TOP/tools/pct/schema_validation/devicetree-validation/dtschema_bin/bin:${PATH}

Generate Schema#

Create a schema-list.yaml file listing the paths to the specification YAML files to use for validation. Specification file locations are listed in Configuration Specification.

- /path/to/Audio_upstream_compatible.yaml
- /path/to/LinuxBSP_upstream_compatible.yaml

Then, generate a combined schema from these files:

dos_auto_verify --make-schema --schema-yaml schema-list.yaml --output schema.json

The tool processes each input YAML specification and merges them into a single JSON schema file. This is a one-time step. The generated schema can be reused across multiple validation runs. Schema processing errors are written to <output>_errors.json.

Argument

Description

--schema-yaml, -s (required)

Path to the YAML file containing a list of specification file paths.

--output, -o (required)

Output file path for the combined JSON schema.

Validate#

DTB validation: Validates property values against data types, ranges, and enums from the upstream specification:

dos_auto_verify --verify-schema --schema-json schema.json --dtb <path-to-dtb> --output validation.log

Multiple DTBs can be passed as space-separated paths:

dos_auto_verify --verify-schema --schema-json schema.json --dtb dtb1.dtb dtb2.dtb --output validation.log

Annotated DTS validation: Checks that customer-configurable properties originate from driveos_customer_config and non-customer-configurable properties do not. The --source-directory argument specifies the base directory used to resolve annotation paths in the DTS:

dos_auto_verify --verify-schema --schema-json schema.json --dts <path-to-dts> --source-directory <base-dir> --output validation.log

Argument

Description

--schema-json, -s (required)

Path to the combined JSON schema file generated by --make-schema.

--dtb, -d

One or more DTB file paths (space-separated). At least one of --dtb or --dts is required.

--dts

One or more annotated DTS file paths (space-separated). At least one of --dtb or --dts is required. Must be used together with --source-directory.

--source-directory

Base directory for resolving annotation paths in DTS files. Required when using --dts.

--output, -o (required)

File path to write the validation log.

--log-type, -t

Controls which results appear in the log: 0 = failures only, 1 = passes only, 2 = both (default).

--whitelist, -w

One or more whitelist YAML file paths (space-separated). Matching validators and device tree paths are excluded from validation results.

Validation Output#

The output is a JSON file containing validation results organized by device tree path, followed by coverage analysis. Each validation-result entry contains:

  • The device tree path as the key.

  • A logs array with one entry per validation check, each containing:

    • validator: The type of check performed (e.g., const, enum, minimum, maximum, etc).

    • calibration_expected: The expected value from the specification.

    • calibration_seen: The actual value found in the DTB.

    • schema_file: The schema file that defines the constraint.

    • status: PASS or FAIL.

    • error_message: A description of the failure (present on FAIL).

  • verification_result: Overall result for the path (PASS or FAIL). Set to FAIL if any check in logs fails.

The output also contains a top-level coverage_analysis entry. This section lists which paths were covered by schema validation and which paths were not:

  • paths_validated: Device tree paths that matched a schema and were validated.

  • paths_not_validated: Device tree paths or properties that did not match a validation schema. Use this list to identify specification coverage gaps or device tree content that may need a schema update.

The following is an example of a failing validation entry:

{
    "bus@0/spi@810c450000/prod-settings/#prod-cells": {
        "logs": [
            {
                "validator": "const",
                "calibration_expected": 4,
                "schema_file": "http://devicetree.org/schemas/tegra264-spi-expanded.yaml#",
                "status": "FAIL",
                "calibration_seen": 5,
                "error_message": "4 was expected"
            }
        ],
        "verification_result": "FAIL",
        "schema": "tegra264-spi-expanded"
    },
    "coverage_analysis": {
        "paths_validated": [
            "/",
            "bus@0/spi@810c450000/prod-settings/#prod-cells"
        ],
        "paths_not_validated": [
            "bus@0/spi@810c450000/undocumented-property"
        ]
    }
}

In this example, the const validator expected the value 4 for the #prod-cells property at node path bus@0/spi@810c450000/prod-settings but found 5 in the DTB. The coverage_analysis section shows the paths that were validated and the paths that were present in the device tree but not validated by a schema.