Quick guide to Debugging Device Tree Generator Issues

The wiki shows how to quickly debug device tree generator issues

Table of Contents


The device tree generator (DTG) is a utility that is most commonly used in PetaLinux to create the device tree. The DTG uses the XSA file from Vivado as an input file to generate the dts files. The DTG can fail for a number of different reasons; invalid HW design, syntax, or other errors in the system-user.dtsi, or in rare events, bug in the tools. Debugging these issues can be cumbersome if using PetaLinux as this takes time to generate the device tree (DT) and compile using the device tree compiler (DTC). This wiki will show how to speed this debug flow by providing scripts that can be run outside of PetaLinux.

Downloading the Device Tree Generator

The device tree generator can be downloaded from the Xilinx Github Repository as shown below:

1 2 3 4 5 mkdir -p repo/my_dtg cd repo/my_dtg git clone https://github.com/Xilinx/device-tree-xlnx cd device-tree-xlnx git checkout xilinx-v2020.1

Using the XSCT to generate the Device Tree

The Xilinx Software Command-line Tool (XSCT) that is delivered in Vitis can be used to create the device tree source files (DTS). This is similar to how PetaLinux creates the DTS. The TCL commands to generate the device tree in XSCT can be seen below:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 proc build_dts {xsa} { hsi::open_hw_design $xsa hsi::set_repo_path ./repo set proc 0 foreach procs [hsi::get_cells -filter {IP_TYPE==PROCESSOR}] { if {[regexp {cortex} $procs]} { set proc $procs break } } if {$proc != 0} { puts "Targeting $proc" hsi::create_sw_design device-tree -os device_tree -proc $proc hsi::generate_target -dir my_dts } else { puts "Error: No processor found in XSA file" } hsi::close_hw_design [hsi::current_hw_design] }

Create a file called build_dts.tcl and copy the contents above into this file.

Since the DTG uses the XSA as an input file, and the XSA only contains IPs that are in the Block Design, then for the same reason the DTS output from the DTG will only have DT nodes for the IP in the BD. A user can add include files to the device tree (similar to how this would be achieved in C/C++). These are called DTSI files. In PetaLinux, users can use the system-user.dtsi template to add, or modify nodes in the DT.

To add a dtsi file to the DT generated in the above build_dts proc, a user can copy the TCL proc below into the build_dts.tcl

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 proc include_dtsi {dtsi_file} { if {[file exists $dtsi_file]} { file copy -force $dtsi_file my_dts set fp [open my_dts/system-top.dts r] set file_data [read $fp] close $fp set fileId [open my_dts/system-top.dts "w"] set data [split $file_data "\n"] foreach line $data { puts $fileId $line } puts $fileId "#include \"$dtsi_file\"" close $fileId } }

Download and compiling the DTC:

1 2 3 4 git clone https://git.kernel.org/pub/scm/utils/dtc/dtc.git cd dtc make export PATH=$PATH:<path to dtc>

Creating A Makefile to build the DTS

XSCT, and other utilities, can be called from a custom made makefile. A template is seen below:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 VERSION ?= 2020.1 XSCT=/proj/gsd/vivado/Vitis/$(VERSION)/bin/xsct dts: $(RM) -r my_dts $(XSCT) -eval "source build_dts.tcl; build_dts $(XSA_FILE)" include_dtsi: $(XSCT) -eval "source build_dts.tcl; include_dtsi $(DTSI_FILE)" compile: $(RM) -r my_dts/system-top.dtb gcc -I my_dts -E -nostdinc -undef -D__DTS__ -x assembler-with-cpp -o my_dts/system-top.dts.tmp my_dts/system-top.dts dtc -I dts -O dtb -o my_dts/system-top.dtb my_dts/system-top.dts.tmp clean: $(RM) -r .Xil my_dts *.bit *.mmi *.c *.h psu_init.tcl ps7_init.tcl *.html

Running the Make File

To create the DTS call the command:

  • make dts XSA_FILE=<Path to XSA FILE>.xsa

To add a DTSI file:

  • make include_dtsi DTSI_FILE=<Your DTSI File>

To compile

  • make compile

Related Links