The wiki shows how to quickly debug device tree generator issues

Table of Contents

Introduction

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:

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:

proc build_dts {xsa} {
	hsi::open_hw_design $xsa
	hsi::set_repo_path ./repo
	set proc 0
	foreach procs [hsi::get_cells -hier -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

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:

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:

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:

To add a DTSI file:

To compile

Related Links