Device tree debugging

On Linux platforms, devices are physically connected to buses and the device tree needs to reflect this for device to be detected.

It is important to debug device tree issues at startup. To achieve this, a very convenient tool is dtc (aka 'device tree compiler').

Keep in mind that any change to the device tree is only taken into account on the next reboot, so changing the device tree means rebooting!

Installing dtc

Installing dtc on the target machine is convenient, but may not be allowed on the target. We describe below an alternative solution, where dtc is installed on another machine.

apt-get install device-tree-compiler

Retrieving the current device tree rather than looking at the sources

The point with device tree is that looking at the sources (.dts/.dtsi) files you don't really have the view the host has on the final device tree.

To cope with this, we recommend looking at the 'device tree seen by the host', directly from the file system at /sys/firmware/devicetree/base/

• This reflects the device tree content after editing/compiling/booting

Retrieving the device tree using dtc

$ dtc --sort -I fs -O dts  /sys/firmware/devicetree/base > device_tree.out

NB: The 'dts' format allows the resulting file to be edited in a human-readable format. If edited as if it were a C file you can benefit from code folding to get a better view of the contents. With the '--sort' option, comparing device trees is much easier.

Retrieving the device tree without dtc support on your platform

• On your platform
  • Create an archive from your file system's device tree

tar zcf device_tree.tar.gz /sys/firmware/devicetree/base/

• Copy this file to a platform supporting dtc
• On a platform supporting dtc
  • decompress the archive
  • retrieve the device tree using dtc from the new directory (note how the path starts with 'sys' instead of '/sys' here, since the entire content has been extracted locally)

tar xvf device-tree.tar.gz
dtc --sort -I fs -O dts sys/firmware/devicetree/base/ > device_tree.out

Retrieving the device tree from the .dtb (device tree blob) file

As a last resort, get the .dtb file used at boot and decompile it using dtc on a platform supporting it.

$ dtc --sort -I dtb -O dts  your_dtb_file.dtb > device_tree.out

NB: Checking the device tree from the file system rather than from the .dtb file is safer, since it removes the risk of using the wrong file. The file system content is 'what the kernel sees'.

Debugging device tree issues by comparison

Once you have 2 different files before/after adding your device tree you can easily diff them and spot all differences brought in by your .dts/.dtsi source files.

In case of potential device tree issues, make sure all the changes you expect are visible, otherwise you may be facing issues in your .dts/.dtsi source files.

Checking device tree at runtime

$ sudo vcdbg log msg

will allow you to check which device tree file is loaded at boot.

Adding 

dtdebug=1

to /boot/config.txt will add more details on the next boot.