Device Tree

Device trees are used by Linux to describe features and address space of memory-mapped hardware. The device tree is compiled from source files with the dtc tool and loaded by U-Boot before starting the Linux kernel.

Red Pitaya FPGA projects use Vivado 2020.1 for hardware design and SDK 2019.1 for software integration. The device tree generation process uses the HSI (Hardware Software Interface) tool with Device Tree Xilinx version 2017.2 to automatically create device tree sources from the Vivado hardware design.

On Red Pitaya, device trees are particularly important for:

  • Configuring PS (Processing System) peripherals

  • Describing custom AXI peripherals in PL (Programmable Logic)

  • Managing GPIO and analog input mappings

  • Configuring signal routing via pinctrl overlays

  • Enabling Linux IIO drivers for XADC analog inputs


Prerequisites

To work with device trees on Red Pitaya, you will need the Device Tree Xilinx repository which provides device tree files for Xilinx Zynq devices.

Automatic Download (Full Ecosystem Build)

When building the complete Red Pitaya ecosystem using the main repository’s Makefile.x86, the Device Tree Xilinx repository is automatically downloaded via:

# In the main RedPitaya repository
make -f Makefile.x86

The Makefile uses curl to download and extract the device tree repository (line 82 of Makefile.x86):

DTREE_URL ?= https://github.com/Xilinx/device-tree-xlnx/archive/$(DTREE_TAG).tar.gz

Manual Setup (Standalone FPGA Build)

When building only FPGA projects using the standalone RedPitaya-FPGA repository, you must manually provide the Device Tree Xilinx repository:

# Navigate to RedPitaya-FPGA directory
cd RedPitaya-FPGA

# Create tmp directory if it doesn't exist
mkdir -p tmp
cd tmp

# Clone the Device Tree Xilinx repository
git clone https://github.com/Xilinx/device-tree-xlnx device-tree-xlnx-xilinx-v2017.2
cd device-tree-xlnx-xilinx-v2017.2
git checkout xilinx-v2017.2

Note

The default device tree version is 2017.2, but this can be configured using the DTS_VER parameter when building FPGA projects. The repository directory name must match the pattern device-tree-xlnx-xilinx-v{version}.

Important

Device tree generation requires Xilinx SDK 2019.1 to be installed and the xsct command to be available in your PATH. See the sdk_install guide for installation instructions.


Device Tree File Types

When working with Red Pitaya FPGA projects, the HSI tool generates several types of device tree files:

Table 4.2 Device Tree Files Generated by Make

File

Description

zynq-7000.dtsi

PS peripherals and interfaces (generated by HSI)

pl.dtsi

AXI peripherals in PL (generated by HSI)

system.dts

Complete system device tree (includes above files)

Note

The HSI tool automatically generates these files based on your Vivado hardware design. All Red Pitaya FPGA projects are configured for Vivado 2020.1, as specified in the project TCL scripts.


Generating Device Trees

From FPGA Build Process

The device tree is automatically generated when building FPGA projects using the Red Pitaya Makefile. The build system uses xsct (Xilinx Software Command-Line Tool) to invoke HSI (Hardware Software Interface) scripts that generate device tree source files from the Vivado hardware design.

The standard FPGA project build process:

cd RedPitaya-FPGA
make PRJ=stream_app MODEL=Z10

This will:

  1. Generate the Vivado hardware design using Vivado 2020.1

  2. Export the hardware definition to SDK

  3. Invoke xsct red_pitaya_hsi_dts.tcl to generate device tree sources

  4. Place the generated device tree files in prj/{project}/sdk/dts/

The Makefile automatically handles the device tree generation with this command:

xsct red_pitaya_hsi_dts.tcl $(PRJ) DTS_VER=$(DTS_VER)

Where DTS_VER defaults to 2017.2 but can be overridden:

make PRJ=stream_app MODEL=Z10 DTS_VER=2018.1

For more details, see the Makefile in the RedPitaya-FPGA repository.

Understanding the HSI Script

The red_pitaya_hsi_dts.tcl script in the RedPitaya-FPGA repository performs the following steps:

  1. Opens the hardware design from sdk/red_pitaya.sysdef

  2. Sets the repository path to the Device Tree Xilinx sources

  3. Creates a device tree software design for ps7_cortexa9_0 processor

  4. Configures the kernel version (matching DTS_VER parameter)

  5. Enables device tree overlay support (dt_overlay true)

  6. Generates device tree sources in sdk/dts/

The script uses this repository path structure:

hsi set_repo_path ../../../tmp/device-tree-xlnx-xilinx-v$ver/

This is why the Device Tree Xilinx repository must be cloned in the tmp/ directory with the specific naming pattern.

The complete HSI command sequence in the script:

hsi open_hw_design $path_sdk/red_pitaya.sysdef
hsi set_repo_path ../../../tmp/device-tree-xlnx-xilinx-v$ver/
hsi create_sw_design device-tree -os device_tree -proc ps7_cortexa9_0
hsi set_property CONFIG.kernel_version $ver [hsi get_os]
hsi set_property CONFIG.dt_overlay true [hsi get_os]
hsi generate_target -dir $path_sdk/dts

See the red_pitaya_hsi_dts.tcl script in the RedPitaya-FPGA repository for the complete implementation.


Compiling Device Trees

Device trees must be compiled from source (.dts/.dtsi) to binary blob (.dtb) format before they can be loaded by U-Boot.

Basic Compilation

Use the device tree compiler (dtc) to compile device tree sources:

dtc -I dts -O dtb -o devicetree.dtb system.dts

Where:

  • -I dts: Input format is device tree source

  • -O dtb: Output format is device tree blob

  • -o devicetree.dtb: Output filename

  • system.dts: Input source file

On Red Pitaya Board

Red Pitaya stores device trees in /opt/redpitaya/dts/ with subdirectories for each board model. You can recompile device trees directly on the board:

root@rp-f01c3d:~# rw
root@rp-f01c3d:~# cd /opt/redpitaya/dts/$(monitor -f)/
root@rp-f01c3d:~# dtc -I dts -O dtb ./dtraw.dts -o devicetree.dtb
root@rp-f01c3d:~# reboot

Note

Always reboot after updating the device tree. Changes are applied when U-Boot loads the new DTB during boot.


Modifying Device Trees

You can modify device tree sources to customize hardware configuration. Common modifications include:

  • Adding custom AXI peripherals

  • Changing GPIO pin assignments

  • Configuring peripheral properties

  • Adding device tree overlays

Editing Device Tree Sources

Device tree source files use a hierarchical structure with nodes representing hardware components:

/ {
    amba {
        gpio@e000a000 {
            compatible = "xlnx,zynq-gpio-1.0";
            reg = <0xe000a000 0x1000>;
            interrupts = <0 20 4>;
        };
    };
};

Always maintain proper indentation and closing braces when editing device tree sources.


Loading Custom Device Trees

Once you have compiled a custom device tree, you can load it on your Red Pitaya board using the overlay script.

Using Overlay Script

The overlay.sh script (OS 2.00+) provides a convenient way to load custom FPGA bitstreams along with their device trees:

overlay.sh v0.94 /root/custom.bit.bin /root/custom.dtbo

This keeps the standard Red Pitaya project name as the board-model anchor while replacing the built-in FPGA and device tree files with your custom paths.

For detailed information on using the overlay script, see:

Manual Loading

For older OS versions or manual control, you can load device trees using the fpgautil tool directly:

fpgautil -b path/to/bitstream.bit.bin -o path/to/devicetree.dtbo

Note

The device tree must be in DTBO (Device Tree Blob Overlay) format for runtime loading. Use the -O dtb option with dtc to generate the correct format.


Troubleshooting

Device Tree Compilation Errors

Error: Syntax errors in device tree source

  • Cause: Malformed DTS syntax, missing braces, or incorrect node structure

  • Solution: Carefully check syntax, ensure all nodes have opening and closing braces, verify indentation

Error: Undefined reference to included file

  • Cause: Missing or incorrect path to included .dtsi files

  • Solution: Verify include paths, ensure all required .dtsi files are present in the same directory or properly referenced

Device Tree Not Loaded

Symptom: Changes to device tree don’t take effect

  • Cause: Device tree not properly compiled or board not rebooted

  • Solution:

    • Verify devicetree.dtb file was updated (check timestamp)

    • Ensure you rebooted the board after updating device tree

    • Check U-Boot console output during boot for device tree loading messages

Symptom: FPGA peripherals not visible in Linux

  • Cause: Device tree doesn’t describe PL peripherals correctly

  • Solution:

    • Verify pl.dtsi was generated from correct Vivado design

    • Check that system.dts includes pl.dtsi

    • Ensure AXI peripheral addresses match hardware design


Additional Resources