Skip to main content

Device Trees and Overlays

A device tree describes the hardware on a board so that the kernel can bind drivers to it. A Modalix board boots a base device tree and then applies overlays for what you attach to it, such as a camera. This page shows how to select an overlay that ships with the release, how to write your own, and how to check the result.

Not yet validated on hardware

This page is written from the kernel and U-Boot sources for platform release 2.1.3 and from the other guides on this site. The steps have not been run on a board as they are written here.

How the Board Loads a Device Tree​

  1. U-Boot loads the base device tree for the board from the active boot directory, boot-0 or boot-1.
  2. U-Boot applies each overlay named in its dtbos variable, in the order listed.
  3. The kernel starts with the merged device tree.

A device tree describes hardware. It does not add a driver. The driver for a device must already be in the kernel or be installed as a module. See the device tree usage model in the kernel documentation.

Select an Overlay from the Release​

The release has overlays for the supported cameras and for PCIe and flash configurations. Their sources are in the overlays directory of the kernel tree.

  1. List the overlays on the board:

    sima@modalix:~$ ls /boot/boot-*/*.dtbo

  2. Interrupt U-Boot, set dtbos to the overlay, and boot:

    sima$ setenv dtbos modalix-som-waveshare-ARDU-IMX477-1CAM.dtbo
    sima$ saveenv
    sima$ boot

To apply more than one overlay, separate the names with spaces. For camera overlays, see Supported MIPI Cameras.

Write Your Own Overlay​

Write an overlay when you attach a device that the release has no overlay for. This example adds an I2C GPIO expander at address 0x27 on I2C bus 0:

/dts-v1/;
/plugin/;

&i2c00 {
    status = "okay";
    clock-frequency = <400000>;
    #address-cells = <1>;
    #size-cells = <0>;

    pcf8574: gpio@27 {
        compatible = "nxp,pcf8574";
        reg = <0x27>;
        gpio-controller;
        #gpio-cells = <2>;
    };
};
  • &i2c00 selects the node to change by its label in the base device tree.
  • status = "okay" enables a node that the base device tree leaves disabled.
  • #address-cells and #size-cells repeat the values of the bus in the base device tree. Without them, dtc warns that it cannot check reg.
  • The child node is the device. compatible selects the driver, and reg is the address of the device on the bus.

Before you write the overlay, check that the kernel has the driver. The compatible string must belong to a driver that simaai_modalix_defconfig enables, or to a module that you build and install.

For a larger example, read a camera overlay from the kernel tree, such as modalix-som-waveshare-ARDU-IMX477-1CAM.dtso. It adds a clock for the sensor, sets up the I2C bus and the power-down pin, enables the CSI interface and its video nodes, and connects the sensor to the CSI interface over two data lanes.

Build and Install the Overlay​

  1. Compile the overlay source to a .dtbo file, as described in Build the BSP from Source.

  2. Copy the .dtbo file to the active boot directory of the board.

  3. Add the file to dtbos in U-Boot, after the overlays that are already listed:

    sima$ env set dtbos $dtbos my-device.dtbo
    sima$ saveenv
    sima$ boot

Check the Result​

Check in this order. Each step depends on the one before it.

  1. The overlay was applied. Find the new node in the device tree that the kernel is using:

    root@modalix:~# find /proc/device-tree -name "gpio@27"

  2. The driver bound to the device. Look for the driver in the kernel log:

    root@modalix:~# dmesg | grep -i pcf857x

  3. The device works. Use the tool for that kind of device. For the GPIO expander, gpiodetect lists a new chip. For a camera, cam -l lists the camera.

If It Does Not Work​

What you seeLikely causeWhat to check
The node is not in /proc/device-treeU-Boot did not apply the overlayprintenv dtbos in U-Boot, the file in the active boot directory, and errors on the U-Boot console
The node is there, but no driver bindsThe kernel has no driver for the compatible stringThe kernel configuration, and dmesg
The driver reports an errorThe bus or the address is wrong, or a clock, supply, reset, or GPIO is missingdmesg, and i2cdetect for an I2C device
Another device stops workingTwo overlays change the same node or the same pinApply one overlay at a time

Next Steps​