NVIDIA Jetson - Device Tree Overlay

Introduction

This wiki is intended to be used as a reference If you want to create a Device Tree (DT) overlay for a custom hardware module. DT overlay is used to configure various hardware devices that may be attached to the system.

Nvidia Jetson kernels use a Device Tree (DT) to describe the hardware present in the Nvidia Jetson board. You can use Jetson‑IO to support a custom hardware module by creating a device tree overlay for the hardware module to allow optional external hardware to be described and configured.

Create a device tree overlay

Jetson‑IO

NVIDIA provides the Jetson Expansion Header Tool (also known as Jetson‑IO), a Python script that runs on a Jetson developer kit and lets you apply a DT overlay configuration through a graphic user interface. Jetson‑IO finds the overlay file and allows you to apply it.

Device tree overlay structure

A device tree overlay for a hardware module must define the property:

• fragment: A DT overlay comprises a number of fragments, each of which targets one node and its subnodes.
• overlay-name: which specifies a name for the hardware module.
• jetson-header-name: which specifies the expansion header with which the hardware module is associated; must specify one of the values described in the table jetson-header-name property values.
• compatible: which indicates which combination of Jetson module and carrier board the overlay supports; must specify one or more of the values described in the table compatible property values.

Creating a Simple Device Tree Overlay

To create a simple device tree overlay to add a new custom property for Jetson Xavier NX Developer Kit and attach it to the 40‑pin expansion header, create a file named my-overlay.dts on the target platform with the following contents:

/dts-v1/;
/plugin/;
 
/ {
    overlay-name = "My Jetson Overlay Example";
    jetson-header-name = "Jetson 40pin Header";
    compatible = "nvidia,p3509-0000+p3668-0001";
 
    fragment@0 {
        target-path = "/";
        __overlay__ {
            my-custom-property = "This Is My Overlay";
        };
    };
};

Enter the following command to compile the DTS source file into an overlay file:

$ dtc -O dtb -o my-overlay.dtbo -@ my-overlay.dts

After you copy the new overlay file to the /boot directory, Jetson‑IO finds the overlay file and allows you to apply it, If you use an incorrect compatible value, the files is not listed

$ sudo cp my-overlay.dtbo /boot
$ sudo /opt/nvidia/jetson-io/config-by-hardware.py -l

Configuration listed from Xavier NX

Configurations for the following hardware modules are available:
1. Adafruit SPH0645LM4H
2. FE-PI Audio V1 and Z V2
3. My Jetson Overlay example
4. ReSpeaker 4 Mic Array

Apply the device tree overlay created

$ sudo /opt/nvidia/jetson-io/config-by-hardware.py -n "My Jetson Overlay example"

Support for hardware modules is handled by device tree overlay files (.dtbo files).