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.

You can use Jetson‑IO to perform 2 task:

1. Configure header pins manually: Displays the expansion header configuration screen, which lets you specify which functions to enable on the header. The application creates the DT overlay and it is applied.
2. Configure for compatible hardware: Displays the compatible hardware screen, which lets you select from a list of configurations for hardware modules that can be attached to the header. You can use pre-created DT overlay for certain hardware or create your custom DT overlay and select it from the list.

This guide uses the second option to apply a custom DT overlay.

Device tree overlay structure

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

• 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.
• fragment: A DT overlay comprises a number of fragments, each of which indicates child nodes and the target.
• target: phandle target of the overlay.
• target-path: target path of the overlay.

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 DT overlay 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"

To apply the changes is required to reboot the board. after reboot the board you can read the new property defined in the device tree using the DT overlay.

cat /proc/device-tree/my-custom-property

Output:

This Is My Overlay

Remove overlay changes applied

The changes of the DT overlay are applied over the DT original and is created a new device tree. The name of the resulting device tree combines the original DT name and the overlay name. /boot/kernel_tegra194-p3668-all-p3509-0000-my-jetson-overlay-example.dtb

To use the new DT, Jetson‑IO creates a new entry in /boot/extlinux/extlinux.conf

This is the new entry added when is added the overlay:

LABEL My Jetson Overlay example
	MENU LABEL My Jetson Overlay example
	LINUX /boot/Image
	FDT /boot/kernel_tegra194-p3668-all-p3509-0000-my-jetson-overlay-example.dtb
	INITRD /boot/initrd
	APPEND ${cbootargs} quiet root=/dev/mmcblk0p1 rw rootwait rootfstype=ext4 console=ttyTCU0,115200n8 console=tty0 fbcon=map:0 net.ifnames=0

Remove this entry from /boot/extlinux/extlinux.conf to avoid to use the new device tree, and reboot the board.

Documentation

Nvidia device tree overlay

Running Jetson-IO