Customizing Device Trees in Xilinx Yocto

Introduction

In a general Yocto development, the ASSP on a target board is fixed and the kernel tree provides the device tree blob (dtb). The device tree can be customized by simply patching the dts in the kernel tree if needed. In fabric-based devices such as Zynq and Zynq Ultrascale+, the IP targeting the fabric is customized during the design. Because the IP in the PL changes per design, the developer needs a way to generate the device tree for the PL at design time. The Xilinx Device Tree Generator (DTG), can parse a hardware description (HDF) and automatically generate dts for your design. Because this dts is regenerated every time you make changes to your PL design, it's difficult to just patch the dts. This wiki shows how to append the device-tree recipe to add a custom dtsi that can override device properties or add new nodes that are board specific. The examples shown are for the ZCU102 platform.

Device Tree Recipe

The meta-xilinx layer includes the device-tree.bb recipe which provides baseline support for machines that are not included in the kernel tree, such as MicroBlaze and Zed boards. The meta-xilinx-tools layer extends this recipe with a device-tree.bbappend to support the DTG. The DTG, Yocto can generate a custom device tree for your design, however, it is still missing board specific device nodes for your target. By further extending the device-tree, you can include a user dtsi which can customize the device tree by overriding properties, adding new properties or adding new device nodes. The device-tree.bbappend listing below provides a simple method for customizing your device tree. You are responsible for writing the system-user.dtsi and placing it in the files directory.

Add Custom Device Tree

device-tree.bbappend

FILESEXTRAPATHS_prepend := "${THISDIR}/files:"

SYSTEM_USER_DTSI ?= "system-user.dtsi"

SRC_URI_append = " file://${SYSTEM_USER_DTSI}"

do_configure_append() {
        cp ${WORKDIR}/${SYSTEM_USER_DTSI} ${B}/device-tree
        echo "/include/ \"${SYSTEM_USER_DTSI}\"" >> ${B}/device-tree/system-top.dts
}

You can place your actual system-user.dtsi or a dummy system-user.dtsi in the files directory. You may also control the actual system-user.dtsi from your machine configuration as shown in the example-zcu102-zynqmp listing below. This way if you don't need a system-user.dtsi, the build will still succeed thanks to the dummy dtsi.

system-user.dtsi (dummy)

/* system-user.dtsi */

example-zcu102-zynqmp

SYSTEM_USER_DTSI = "/<path-to>/system-user.dtsi"

Add Existing BSP

The above bbappend allows you to plug your custom device tree nodes into your build. However, you may want to take advantage of work already done for you on an evaluation platform. XSDK and XSCT use YAML to control the build of a BSP. This will pull in a board specific dtsi to support the BSP of your target. For example, this may include an Ethernet PHY device node and I2C extender nodes for the ZCU102. In order to include this BSP support, you need to set the YAML_DT_BOARD_FLAGS flag for your target either in a machine configuration or in a device-tree.bbappend. Note that when specifying in the device-tree.bbappend, it is a good idea to use the machine override syntax so the build system can still build multiple targets.

example-zcu102-zynqmp.conf

YAML_DT_BOARD_FLAGS = "{BOARD zcu102-rev1.0}"

device-tree.bbappend

YAML_DT_BOARD_FLAGS_example-zcu102-zynqmp = "{BOARD zcu102-rev1.0}"

A list of available BOARD definitions can be found in meta-xilinx-tools/recipes-bsp/device-tree/device-tree.bbappend.

Deploy Directory

After a build, your dtb is in the deploy directory with the other images. The deploy directory can get pretty cluttered, however, many of the files are simply links with compact names to the most recent file version with a more verbose name.

The deploy listings below shows the dtb from a zcu102-based build. You may notice multiple deployed dtb from your build. In the first listing, there are three dtb files, but note two of them are simply links to the actual dtb. The dtb is generated from the kernel-devicetree class. This is the same dtb that would be generated from the kernel tree. So this is a fully functional dtb, but it does not include any device tree nodes from your PL design, This is often a good place to fallback if your kernel hangs when you load a custom device tree supporting your PL design. If your kernel boots with this dtb, then you can assume you have a device tree issue in the PL.

dtb from kernel

Image--4.14-xilinx-v2018.2+git0+ad4cd988ba-r0-zynqmp-zcu102-rev1.0-<timestamp>.dtb
Image-zynqmp-zcu102-rev1.0.dtb -> Image--4.14-xilinx-v2018.2+git0+ad4cd988ba-r0-zynqmp-zcu102-rev1.0-<timestamp>.dtb
zynqmp-zcu102-rev1.0.dtb -> Image--4.14-xilinx-v2018.2+git0+ad4cd988ba-r0-zynqmp-zcu102-rev1.0-<timestamp>.dtb

This listing shows the deployed dtb generated by the DTG. This includes support for your PL design.

dtb from DTG

example-zcu102-zynqmp-system-<timestamp>.dtb
example-zcu102-zynqmp-system.dtb -> example-zcu102-zynqmp-system-<timestamp>.dtb

uEnv.txt

If you are booting from an SD card and using uEnv.txt to set your u-boot environment variables, you need to be aware that the default FDT is the kernel FDT. If you want to boot with the FDT from the DTG, then you can replace the kernel FDT with the DTG FDT in your <machine>.conf or local.conf.

example-zcu102-zynqmp.conf

IMAGE_BOOT_FILES_remove = "${KERNEL_IMAGETYPE}-zynqmp-zcu102-rev1.0.dtb"
IMAGE_BOOT_FILES_append = " ${MACHINE}-system.dtb"

Device Tree Source

If you want to view the dts that generated the dtb, you can either look at the working directory for the device-tree for your machine or you can reverse the dtb with the device tree compiler (dtc). The listing below shows the structure of the build directory for the device-tree. In the build directory you will see the system-top device tree blob (dtb), device tree source (dts) and the output of the C preprocessor (pp). Inside of the device-tree directory you will see the individual files that makeup the final device tree.

device-tree

$ cd tmp/work/example_zcu102_zynqmp-xilinx-linux/device-tree/xilinx+gitAUTOINC+f38738e568-r0/build
$ tree
.
├── device-tree
│   ├── Base_Zynq_MPSoC_wrapper.bit
│   ├── device-tree.mss
│   ├── hardware_description.hdf
│   ├── pcw.dtsi
│   ├── pl.dtsi
│   ├── psu_init.c
│   ├── psu_init_gpl.c
│   ├── psu_init_gpl.h
│   ├── psu_init.h
│   ├── psu_init.html
│   ├── psu_init.tcl
│   ├── system-top.dts
│   ├── system-user.dtsi
│   ├── zcu102-rev1.0.dtsi
│   ├── zynqmp-clk-ccf.dtsi
│   └── zynqmp.dtsi
├── system-top.dtb
├── system-top.dts
└── system-top.dts.pp

The listing below shows how to reverse the final dtb assuming you have installed the dtc and it's in your path. The output is system.dts.

dtc

$ dtc -I dtb -O dts -o system.dts example-zcu102-zynqmp-system.dtb

Xilinx Wiki