This page covers the generation of devicetree source (DTS) files using Xilinx tools as well as the building/compiling of these source files using standard open-source tools. In particular, use of the Xilinx Devicetree Generator (DTG) will be covered for generating DTS files from a Xilinx hardware project while the devicetree compiler (DTC) will be covered for compiling DTS files into a devicetree binary (DTB). Although the primary use of the DTB is to provide it to the Linux kernel so that Linux can be initialized to specific hardware correctly, the DTB can also be used with QEMU to emulate hardware for both Linux and standalone systems.
Table of Contents
Table of Contents exclude Table of Contents
Child Pages
Child pages (Children Display)
Devicetree 101
What is devicetree?
Linux uses the DT basically for platform identification, run-time configuration like bootargs and the device node population.
Devicetree Basics
Each driver or a module in the device tree is defined by the node and all its properties are defined under that node. Based on the driver it can have child nodes or parent node.
For example a device connected by SPI bus will have SPI bus controller as its parent node and that device will be one of the child node of spi node. Root node is the parent for all the nodes.Under the root node typically consists of
1) CPUs node information
2) Memory information
3) Chosen can have configuration data like the kernel parameters string and the location of an initrd image
4) Aliases
5) Nodes which define the buses information
Devicetree Syntax Example
language | bash |
---|---|
theme | Midnight |
title | zynqmp-example.dtsi |
This page covers the generation of devicetree source (DTS) files using Xilinx tools as well as the building/compiling of these source files using standard open-source tools. In particular, use of the Xilinx Devicetree Generator (DTG) will be covered for generating DTS files from a Xilinx hardware project while the devicetree compiler (DTC) will be covered for compiling DTS files into a devicetree binary (DTB). Although the primary use of the DTB is to provide it to the Linux kernel so that Linux can be initialized to specific hardware correctly, the DTB can also be used with QEMU to emulate hardware for both Linux and standalone systems.
Table of Contents
Table of Contents exclude Table of Contents
Child Pages
Child pages (Children Display)
Devicetree 101
What is devicetree?
Linux uses the DT basically for platform identification, run-time configuration like bootargs and the device node population.
Devicetree Basics
Each driver or a module in the device tree is defined by the node and all its properties are defined under that node. Based on the driver it can have child nodes or parent node.
For example a device connected by SPI bus will have SPI bus controller as its parent node and that device will be one of the child node of spi node. Root node is the parent for all the nodes.Under the root node typically consists of
1) CPUs node information
2) Memory information
3) Chosen can have configuration data like the kernel parameters string and the location of an initrd image
4) Aliases
5) Nodes which define the buses information
Devicetree Syntax Example
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
/ { compatible = "xlnx,zynqmp"; #address-cells = <2>; #size-cells = <2>; cpus { #address-cells = <1>; #size-cells = <0>; cpu0: cpu@0 { compatible = "arm,cortexa53", "arm,armv8"; device-type = "cpu"; enable-method = "psci"; operating-points-v2 = <&cpu_opp_table>; reg = <0x0>; cpu-idle-states = <&CPU_SLEEP_0>; }; cpu1: cpu@1 { compatible = "arm,cortexa53", "arm,armv8"; device-type = "cpu"; enable-method = "psci"; operating-points-v2 = <&cpu_opp_table>; reg = <0x1>; cpu-idle-states = <&CPU_SLEEP_0>; }; }; chosen { bootargs = "earlycon clk_ignore_unused"; }; memory { device-type = "memory"; reg = <0x0 0x0 0x0 0x80000000>, <0x00000008 0x0 0x0 0x80000000>; }; amba_apu: amba_apu@0 { compatible = "simple-bus"; #address-cells = <2>; #size-cells = <1>; ranges = <0 0 0 0 0xffffffff>; gic: interrupt-controller@f9010000 { compatible = "arm,gic-400", "arm,cortex-a15-gic"; #interrupt-cells = <3>; reg = <0x0 0xf9010000 0x10000>, 0x0 0xf9020000 0x20000>, 0x0 0xf9040000 0x20000>, 0x0 0xf9060000 0x20000>, interrupt-controller; interrupt-parent = <&gic>; interrupts =<1 9 0xf04>; }; }; amba: amba { regcompatible = <0x0 0xf9010000 0x10000>, "simple-bus"; #address-cells = <2>; #size-cells = <2>; ranges; 0x0 0xf9020000 0x20000>, can0: can@ff060000 { 0x0compatible 0xf9040000= 0x20000>,"xlnx,zynq-can-1.0"; clock-names = "can_clk", "pclk"; 0x0 0xf9060000 0x20000>, reg =<0x0 0xff060000 0x0 0x1000>; interrupts = interrupt-controller;<0 23 4>; interrupt-parent = <&gic>; tx-fifo-depth = <0x40>; interrupts =<1 9 0xf04>; rx-fifo-depth = }<0x40>; }; amba: amba { compatiblepower-domains = "simple-bus";<&pd_can0>; #address-cells = <2>; #size-cells = <2>; ranges; can0: can@ff060000 { compatible = "xlnx,zynq-can-1.0"; clock-names = "can_clk", "pclk"; reg =<0x0 0xff060000 0x0 0x1000>; interrupts = <0 23 4>; interrupt-parent = <&gic>; tx-fifo-depth = <0x40>; rx-fifo-depth = <0x40>; power-domains = <&pd_can0>; }; }; |
Devicetree Properties
compatible: The top-level compatible property typically defines a compatible string for the board, and then for the SoC.Values always given with the most-specific first, to least-specific last.
#address-cells: Property indicate how many cells (i.e 32 bits values) are needed to form the base address part in the reg property.
#size-cells: The size part of the reg property.
interrupt-controller: Is a boolean property that indicates that the current node is an interrupt controller.
#interrupt-cells: Indicates the number of cells in the interrupts property for the interrupts managed by the selected interrupt controller.
interrupt-parent: Is a phandle that points to the interrupt controller for the current node. There is generally a top-level interrupt-parent definition for the main interrupt controller.
Devicetree Generator (DTG)
The DTG is intended to help users build their hardware-specific DTS file. Building a DTS for custom hardware will always be a somewhat manual process but the DTG can help jump-start users to a fairly advanced starting point. This is because a lot of information captured in a DTS can be extracted from information in the hardware hand-off file (XSA). DTG will populate various DTS files with as much information as it can based on a supplied XSA file and then the user will be expected to fill-in the blanks or adjust as needed.
Warning | ||
---|---|---|
| ||
The procedure for using the DTG varies for older versions of Xilinx tools. Additionally, for some tool versions, there may be GUI flows versus CLI flows. The "Generate DTS Files" section below provides several sub-sections for each of these different procedures. If you're not using the latest version of Xilinx tools make sure you refer to the appropriate sub-section beyond the first one presented. |
Task Dependencies (Pre-requisites)
XSA Hardware hand-off file generated by Xilinx Vivado tool (previously HDF)
- Xilinx Vitis installation (or previously Xilinx SDK)
Task Output Products
The DTG generates DTS files with *.dts and *.dtsi file extensions. There will be a single top-level *.dts file with "include" statements to reference separate DTS include (DTSI) files. Using DTSI files allows information to be organized amongst different files. For example, as described in more detail below, one DTSI can be used to describe fixed hardware (i.e. fixed in silicon) while another DTSI can be used to describe dynamic hardware (i.e. IP in the programmable logic).
...
};
}; |
Devicetree Properties
compatible: The top-level compatible property typically defines a compatible string for the board, and then for the SoC.Values always given with the most-specific first, to least-specific last.
#address-cells: Property indicate how many cells (i.e 32 bits values) are needed to form the base address part in the reg property.
#size-cells: The size part of the reg property.
interrupt-controller: Is a boolean property that indicates that the current node is an interrupt controller.
#interrupt-cells: Indicates the number of cells in the interrupts property for the interrupts managed by the selected interrupt controller.
interrupt-parent: Is a phandle that points to the interrupt controller for the current node. There is generally a top-level interrupt-parent definition for the main interrupt controller.
Devicetree Generator (DTG)
The DTG is intended to help users build their hardware-specific DTS file. Building a DTS for custom hardware will always be a somewhat manual process but the DTG can help jump-start users to a fairly advanced starting point. This is because a lot of information captured in a DTS can be extracted from information in the hardware hand-off file (XSA). DTG will populate various DTS files with as much information as it can based on a supplied XSA file and then the user will be expected to fill-in the blanks or adjust as needed.
Warning | ||
---|---|---|
| ||
The procedure for using the DTG varies for older versions of Xilinx tools. Additionally, for some tool versions, there may be GUI flows versus CLI flows. The "Generate DTS Files" section below provides several sub-sections for each of these different procedures. If you're not using the latest version of Xilinx tools make sure you refer to the appropriate sub-section beyond the first one presented. |
Task Dependencies (Pre-requisites)
XSA Hardware hand-off file generated by Xilinx Vivado tool (previously HDF)
- Xilinx Vitis installation (or previously Xilinx SDK)
Task Output Products
The DTG generates DTS files with *.dts and *.dtsi file extensions. There will be a single top-level *.dts file with "include" statements to reference separate DTS include (DTSI) files. Using DTSI files allows information to be organized amongst different files. For example, as described in more detail below, one DTSI can be used to describe fixed hardware (i.e. fixed in silicon) while another DTSI can be used to describe dynamic hardware (i.e. IP in the programmable logic).
Generally for the SOCs there will be a static dts/dtsi files, but when it comes to the FPGA there can be many complicated designs which the peripheral logic(PL) IPs may vary or might be having different configurations.
For these complicated FPGA designs we require a Device tree generator(DTG) where it can generate the dts/dtsi automatically for those designs.
Once we generate there will be different files available in the output directory, say for example pl.dtsi, pcw.dtsi, system-top.dts, zynqmp.dtsi, zynqmp-clk-ccf.dtsi, pl-partial-*.dtsi(the suffix of rprm will be added and this files will get generated only for partial/dfx xsa files). These files are described below.
- pl.dtsi: This is a file where all the memory mapped peripheral logic(PL) IP nodes will be available.
- pcw.dtsi: This is a file where the dynamic properties where the PS peripheral needs.
- system-top.dts: This is a file where it contains the memory information, early console and the boot arguments.
- zynqmp.dtsi: This file contains all the PS peripheral information and also the cpu info.
- zynqmp-clk-ccf.dtsi: This file contains all the clock information for the peripheral IPs.
- pl-partial-<RPRM>.dtsi: This is a file where all the memory mapped IP nodes for dynamic function exchange designs(DFX).
- pl-partial-custom-<RPRM>.dtsi: This is a file where we can customize the dfx ip nodes. This will get generated when CONFIG.partial_overlay_custom_dts is set
- If user issues %xsct set_property CONFIG.partial_overlay_custom_dts "pl-partial-final.dts" command then pl-partial-<RPRM>.dtsi and pl-partial-custom-<RPRM>.dtsi will get created and included in pl-partial-final<RPRM>.dts
- user should do his changes in pl-partial-custom-<RPRM>.dtsi. With this user can create pl-partial-<rprm>.dtbo or pl-partial-final<RPRM>.dtbo based on his requirements.
- pl-custom.dtsi: This will get generated only when CONFIG.overlay_custom_dts is set. This flag is useful when user want to customize pl.dtsi nodes with user changes when using overlays.
- If user issues %xsct set_property CONFIG.overlay_custom_dts "pl-final.dts" command then pl.dtsi and pl-custom.dtsi will get created and included in pl-final.dts
- user should do his changes in pl-custom.dtsi. With this user can create pl.dtbo or pl-final.dtbo based on his requirements.
Apart from these files, based on the board it will generate one more board.dtsi file under the same output directory dt/. For example, if board is zcu111-reva then it generates dt/zcu111-reva.dtsi.
...
Code Block | ||
---|---|---|
| ||
git clone https://github.com/Xilinx/device-tree-xlnx cd device-tree-xlnx git checkout <xilinx-v201X_rel_v20XX.X> |
In the last command above <xilinx-v201Xv20XX.X> should be replaced with a valid tag value (for example "xilinx-v2019.2_rel_v2023.1"). Available tags can be listed using the command "git tag".
...
- Source Xilinx design tools
Run XSCT (available as of 2015.1 tool release)
Code Block theme Midnight xsct
Open XSA/HDF file
Code Block theme Midnight hsi open_hw_design <design_name>.<xsa|hdf>
Set repository path (clone done in previous step in SDK) (On Windows use this format set_repo_path {C:\device-tree-xlnx})
Code Block theme Midnight hsi set_repo_path <path to device-tree-xlnx repository>
Create SW design and setup CPU. The -proc option should be followed be is typically one of these values: for Versal "psv_cortexa72_0", for ZynqMP "psu_cortexa53_0", for Zynq-7000 "ps7_cortexa9_0", for Microblaze "microblaze_0".
Code Block theme Midnight _cortexa9_0", for Microblaze "microblaze_0". However, users should extract the processor cell name this as shown below. This will return a list of valid processors that users should use.
Code Block theme Midnight set procs [hsi get_cells -hier -filter {IP_TYPE==PROCESSOR}] puts "List of processors found in XSA is $procs" hsi create_sw_design device-tree -os device_tree -proc psv_cortexa72_0
Generate DTS/DTSI files to folder my_dts where output DTS/DTSI files will be generated
Code Block theme Midnight hsi generate_target -dir my_dts
Clean up.
Code Block theme Midnight hsi close_hw_design [hsi current_hw_design] exit
Note that to compliment XSCT User Guide documentation some tips on using HSI can be found here: HSI debugging and optimization techniques. For example, a command that lists all processor cells in the hardware design can be found there (i.e. IP_TYPE==PROCESSOR); these processor cell names represent valid values for the -proc option in step 5 above.
...
Code Block | ||
---|---|---|
| ||
...
/ {
lmb_bram: memory@0 {
device_type = "memory";
reg = < 0x0 0x10000000 >;
} ;
... |
DTG Limitations
...
0x10000000 >;
} ;
... |
DTG Limitations
- zynqmp-clk-ccf.dtsi has static clock node configuration, if user wants to change any of the clock information update those in system-user.dtsi.
- DTG doesn't support IP that are packaged in a subsystem(multiple BD's)
- Interrupt port width more than one wont be supported.
- When multicore is enabled for the MAC IPs(if the MAC IPs are more than 1) then there is issue with the label in DTG and it fails. But there wont be an issue if the MAC IP is one and multicore is enabled.
- DTG wont support for generation of private peripheral interrupts(PPI).
- DTG supports the video pipeline generation based on the internal TRD designs as mentioned in the wiki https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/25329832/Zynq+UltraScale+MPSoC+VCU+TRD+2018.3
- DTG doesn't support IP that are packaged in a subsystem(multiple BD's)
- Interrupt port width more than one wont be supported.
- When multicore is enabled for the MAC IPs(if the MAC IPs are more than 1) then there is issue with the label in DTG and it fails. But there wont be an issue if the MAC IP is one and multicore is enabled.
- DTG wont support for generation of private peripheral interrupts(PPI).
- DTG supports the video pipeline generation based on the internal TRD designs as mentioned in the wiki https://xilinx-wiki.atlassian.net/wiki/spaces/A/pages/25329832/Zynq+UltraScale+MPSoC+VCU+TRD+2018.3
- DTG doesn't support custom IP, For Multimedia use case If there are any custom IPs connected between the video pipeline IPs DTG wont support those, user may need to add the input and output ports.
- For broadcaster IP the output can connect to multiple output ports and DTG cant know which output port is a valid for the correct pipeline.
- If there are multiple similar video pipelines in the design user need to add the input and output port information in the nodes. The below wiki gives some info about how to add the input and output ports.
- DTG doesn't support non memory-mapped IP's.
- With the current DTG implementation not able to populate the ttc timer properties in pcw.dtsi even if the design has ttc ips. In board dtsi file zynq-7000.dtsi/zynqmp.dtsi/versal.dtsi change the ttc timer name to ttctimer then you will see the entries in pcw.dtsi. We will fix this in 2022.2 release.
- when there are multi ethernet ips in the zynqmp design then getting syntax error for the third IP. Closing the clock with ">" resolves the issue in pl.dtsi file
- if the same peripheral connected to both RPU and APU and you want only RPU to access that please disable the status explicitly 'status = "disabled"' as DTG default generates the nodes for all the accessible peripherals.
New Features:
- Multi concat block support added
- Added DPU IP support
- Replaced the hardcoded values with the macros for reset and power.
- Added dma channels for axi_mcdma IP support in DTG.
- Generate the memory node for each axi_noc IP for Versal
- Added dfx support in DTG
- generating the aie clock node for versal designs if they have aie ip.
- For aie node you can find the detailed doc in below
- custom IP, For Multimedia use case If there are any custom IPs connected between the video pipeline IPs DTG wont support those, user may need to add the input and output ports.
- For broadcaster IP the output can connect to multiple output ports and DTG cant know which output port is a valid for the correct pipeline.
- If there are multiple similar video pipelines in the design user need to add the input and output port information in the nodes. The below wiki gives some info about how to add the input and output ports.
- DTG doesn't support non memory-mapped IP's.
- With the current DTG implementation not able to populate the ttc timer properties in pcw.dtsi even if the design has ttc ips. In board dtsi file zynq-7000.dtsi/zynqmp.dtsi/versal.dtsi change the ttc timer name to ttctimer then you will see the entries in pcw.dtsi. We will fix this in 2022.2 release.
- when there are multi ethernet ips in the zynqmp design then getting syntax error for the third IP. Closing the clock with ">" resolves the issue in pl.dtsi file
- if the same peripheral connected to both RPU and APU and you want only RPU to access that please disable the status explicitly 'status = "disabled"' as DTG default generates the nodes for all the accessible peripherals.
- If PS ethernet is connected to gmii-to-rgmii Interface User should add 'phy1' node references into either board dtsi file or system-user.dtsi files to not see the below build failures. This cannot be autogenerated as DTG doesn't know the connected board phy info.
ERROR (phandle_references): /axi/ethernet@ff0c0000/mdio/gmii_to_rgmii_1@8: Reference to non-existent node or label "phy1"
ERROR: Input tree has errors, aborting (use -f to force output)
Reference node can be found at https://github.com/Xilinx/device-tree-xlnx/blob/xlnx_rel_v2022.2/device_tree/data/kernel_dtsi/2022.2/BOARD/zcu1275-revb.dtsi#L54-L74
New Features:
- Multi concat block support added
- Added DPU IP support
- Replaced the hardcoded values with the macros for reset and power.
- Added dma channels for axi_mcdma IP support in DTG.
- Generate the memory node for each axi_noc IP for Versal
- Added dfx support in DTG
- generating the aie clock node for versal designs if they have aie ip.
- For aie node you can find the detailed doc in below
- https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/soc/xilinx/xlnx%2Cai-engine.yaml
List of drivers supported in the DTG and their bindings in Linux tree
- can, canfd
- axi_cdma
- axi_dma
...
...
...
...
List of drivers supported in the DTG and their bindings in Linux tree
can, canfd- axi_emc
- axi_ethernet, axi_10g_ethernet,xxv_ethernet
- axi_cdmagpio
- axi_dmaiic
- axi_emcaxi_ethernetpcie,axi_10g_ethernet,xxv_ethernetpcie3,xdma
axi_gpiopci/xlnx%2Caxi-pcie-host.yaml
- axi_perf_mon
- axi_quad_iicspi
- axi_pcie,sysace
- axi_pcie3,xdmatft
- axi_perftimebase_monwdt
- axi_quadtraffic_spigen
- axi_sysaceaxiusb2_tftdevice
axi_timebase_wdtyaml
- vcu
- axi_traffic_genvdma
- axixadc_usb2_devicewiz
- vcuaxi_intc
axi_vdmainterrupt-controller/xilinx%2Cintc.txt
- ddr4,ddr3,mig_7series
- pr_decoupler
- usp_rf_data_converter
- axi_timer
- tsn_endpoint_ethernet_mac
- xadcaxi_wizuartlite
axi_intcserial/uartlite.c
- axi_uart16550
- framebuf_rd/framebuf_wr
Bindings from the Linux
...
...
- ddr4,ddr3,mig_7series
- pr_decoupler
- usp_rf_data_converter
- axi_timer
- tsn_endpoint_ethernet_mac
- sdi_rx subsystem Bindings from the Linux
...
...
...
- axi_uartlite
- mipi csi2 rx subsystem Bindings from the Linux
...
...
...
...
- axi_uart16550
...
- framebuf_rd/framebuf_wryaml
- demosaic Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-demosaic.txt
- gamma
Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/dmamedia/xilinx/xilinx_frmbufxlnx%2Cv-gamma-lut.txt - sdi_rx subsystem multiscaler Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Csdirxssxlnx%2Cv-multi-scaler.txt
- mipi csi2 rx subsystem scaler Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Ccsi2rxssxlnx%2Cv-scaler.txt
- demosaic scene change detector Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-demosaicscd.txt
- gamma video timing controller(vtc) Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-gamma-luttc.txt
- multiscaler video test pattern generator(TPG) Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-multi-scalertpg.txt
- scaler color space converter(CSC) Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-scalervpss-csc.txt
- scene change detector vpss scaler Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-scdvpss-scaler.txt
- video timing controller(vtc)sdi_tx subsystem Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master11fb963a44f50af56ff7017fe808ff83b3ae4716/Documentation/devicetree/bindings/mediadisplay/xilinxxlnx/xlnx%2Cvxlnx%2Csdi-tctx.txt
- video test pattern generator(TPG)dsi Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master11fb963a44f50af56ff7017fe808ff83b3ae4716/Documentation/devicetree/bindings/mediadisplay/xilinxxlnx/xlnx%2Cv-tpgxlnx%2Cdsi.txt
- color space converter(CSC)hdmi tx Bindings from the Linux tree Bindings https://github.com/Xilinx/linuxhdmi-xlnxmodules/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-vpsshdmi-tx-cscss.txtvpss scaler
- hdmi rx Bindings from the Linux tree Bindings https://github.com/Xilinx/linuxhdmi-xlnxmodules/blob/master/Documentation/devicetree/bindings/media/xilinx/xlnx%2Cv-hdmi-vpssrx-scalerss.txt
- sdi_tx subsystem Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/drm/xilinx/sdi.txt
- dsi Bindings from the Linux tree https://github.com/Xilinx/linux-xlnx/blob/master/Documentation/devicetree/bindings/drm/xilinx/dsi.txt
- hdmi tx Bindings https://github.com/Xilinx/hdmi-modules/blob/master/Documentation/devicetree/bindings/xlnx%2Cv-hdmi-tx-ss.txt
- hdmi rx Bindings https://github.com/Xilinx/hdmi-modules/blob/master/Documentation/devicetree/bindings/xlnx%2Cv-hdmi-rx-ss.txt
Compiling Devicetree Sources
This section describes the process of using the devicetree compiler (DTC) to compile devicetree sources into a devicetree blob (DTB). Device Tree Blob is a part of the Xilinx design flow described in Getting Started.
Step 1: Fetch Devicetree Compiler Source
Below are commands that can be used to fetch the DTC directly from its Git repository. Alternatively, DTC is supplied as part of the Linux source. For example, if the Xilinx Linux source directory is available the DTC would be found at linux-xlnx/scripts/dtc.
The dtc verson we used and validated was 1.6.1
Code Block | ||
---|---|---|
| ||
git clone https://git.kernel.org/pub/scm/utils/dtc/dtc.git
cd dtc
make
export PATH=$PATH:/<path-to-dtc>/dtc |
Step 2: Pre-processing Devicetree Sources
As covered in the previous section, the DTG produces multiple devicetree files and links them together using "#include" directives. Before this devicetree source can be fed to the compiler (DTC) the top-level DTS must be pre-processed to consolidate all sources into a single DTS. This can be done using a standard GNU C compiler. For example:
Code Block | ||
---|---|---|
| ||
gcc -I my_dts -E -nostdinc -undef -D__DTS__ -x assembler-with-cpp -o system.dts system-top.dts |
Step 3: Compiling a Devicetree Blob (.dtb) file from the DTS
...
Code Block | ||
---|---|---|
| ||
cd /<path-to-dtc>/dtc
dtc -I dts -O dtb -o system.dtb system.dts |
...
Code Block | ||
---|---|---|
| ||
dtc -I dtb -O dts -o system.dts system.dtb |
Miscellaneous Topics
The following sections assume you have the Linux source available.
Alternative: For ARM only
In the Linux source directory, making the target 'dtbs' will compile all DTS files from linux-xlnx/arch/arm/boot/dts/ into DTB files.
Code Block | ||
---|---|---|
| ||
make ARCH=arm dtbs |
...
Code Block | ||
---|---|---|
| ||
make ARCH=arm <devicetree name>.dtb |
Devicetree Binarys Comparision
Linux source also includes a script for DTB comparisons. We can check the differences between two devicetree blobs (DTB files) using the dtx_diff binary as below.
Code Block | ||
---|---|---|
| ||
cd linux-xlnx/scripts/dtc
make ARCH=arm <devicetree name>.dtb
dtx_diff system1.dtb system2.dtb |
Advanced DTG Topics
...
Compiling Devicetree Sources
This section describes the process of using the devicetree compiler (DTC) to compile devicetree sources into a devicetree blob (DTB). Device Tree Blob is a part of the Xilinx design flow described in Getting Started.
Step 1: Fetch Devicetree Compiler Source
Below are commands that can be used to fetch the DTC directly from its Git repository. Alternatively, DTC is supplied as part of the Linux source. For example, if the Xilinx Linux source directory is available the DTC would be found at linux-xlnx/scripts/dtc.
The dtc verson we used and validated was 1.6.1
Code Block | ||
---|---|---|
| ||
git clone https://git.kernel.org/pub/scm/utils/dtc/dtc.git
cd dtc
make
export PATH=$PATH:/<path-to-dtc>/dtc |
Step 2: Pre-processing Devicetree Sources
As covered in the previous section, the DTG produces multiple devicetree files and links them together using "#include" directives. Before this devicetree source can be fed to the compiler (DTC) the top-level DTS must be pre-processed to consolidate all sources into a single DTS. This can be done using a standard GNU C compiler. For example:
Code Block | ||
---|---|---|
| ||
gcc -I my_dts -E -nostdinc -undef -D__DTS__ -x assembler-with-cpp -o system.dts system-top.dts |
Step 3: Compiling a Devicetree Blob (.dtb) file from the DTS
Once the DTC is available, the tool may be invoked to generate the DTB, where "system.dts" is the aggregate devicetree source that resulted from pre-processing.
Code Block | ||
---|---|---|
| ||
cd /<path-to-dtc>/dtc
dtc -I dts -O dtb -o system.dtb system.dts |
Code Block | ||
---|---|---|
| ||
dtc -I dtb -O dts -o system.dts system.dtb |
Miscellaneous Topics
The following sections assume you have the Linux source available.
Alternative: For ARM only
In the Linux source directory, making the target 'dtbs' will compile all DTS files from linux-xlnx/arch/arm/boot/dts/ into DTB files.
Code Block | ||
---|---|---|
| ||
make ARCH=arm dtbs |
The compiled DTB files will be located in linux-xlnx/arch/arm/boot/dts/.
A single linux-xlnx/arch/arm/boot/dts/<devicetree name>.dts may be compiled into linux-xlnx/arch/arm/boot/dts/<devicetree name>.dtb:
Code Block | ||
---|---|---|
| ||
make ARCH=arm <devicetree name>.dtb |
Devicetree Binarys Comparision
Linux source also includes a script for DTB comparisons. We can check the differences between two devicetree blobs (DTB files) using the dtx_diff binary as below.
Code Block | ||
---|---|---|
| ||
cd linux-xlnx/scripts/dtc
make ARCH=arm <devicetree name>.dtb
dtx_diff system1.dtb system2.dtb |
Advanced DTG Topics
How to generate dfx supported dtsi files (only for versal)
This section explains how to generate the dtsi files that supports dfx flow.
1.clone the device-tree
https://github.com/Xilinx/device-tree-xlnx.git -b xlnx_rel_v2023.1
2.launch xsct
i.xsct % setws <workspace dir name>
ii.xsct % repo -set <above cloned device-tree-xlnx path>
iii.xsct % platform create -name dev -hw <static xsa path> -rm-hw <rp-rm xsa path> -proc <proc> -os device_tree
iv.xsct % bsp config dt_overlay true
v.xsct % platform generate
you will find static and partial dtsi files in the <workspace dir>/dev/psv_cortexa72_0/device_tree_domain/bsp/
convert them into dtbo files using the compiling steps.
Note: DTG will generate the dtsi files for rp-rm.xsa only if it has any memory mapped PL IPs.
How to generate full PL soc boot flow (only for versal)
This section explains how to generate the dtsi files to load the full pl once the target is up.
1.clone the device-tree
https://github.com/Xilinx/device-tree-xlnx.git -b xlnx_rel_v2023.1
2.launch xsct
xsct % setws <dtws>
xsct % repo -set device-tree-xlnx
xsct % platform create -name dev -hw static.xsa -rm-hw rp0.xsa -proc versal_cips_psv_cortexa72_0 -os device_tree
xsct % bsp config dt_overlay true
xsct % bsp config classic_soc true
xsct % platform generate
How to customize the dfx dtsi files (only for versal)
This section explains how to generate customize the dtsi files that supports dfx flow.dfx dtsi
1.clone the device-tree
https://github.com/Xilinx/device-tree-xlnx.git -b xlnx_rel_v2022v2023.1
2.launch xsct
i.xsct % setws <workspace dir name>
ii.xsct % setws <dtws>
xsct % repo -set <above cloned device-tree-xlnx path>
iii.xsct % platform % platform create -name dev -hw <static static.xsa path> -rm-hw <rp-rm rp0.xsa path> -proc <proc> versal_cips_psv_cortexa72_0 -os device_tree
iv.xsct % bsp % bsp config dt_overlay truev.
xsct % platform generate
you will find static and partial dtsi files in the <workspace dir>/dev/psv_cortexa72_0/device_tree_domain/bsp/
convert them into dtbo files using the compiling steps.bsp config partial_overlay_custom_dts "pl-partial-final"
xsct % platform generate
How to enable DT OVERLAY from DTG
...
Using HSI commands
1.Clone the device tree repo
https://github.com/Xilinx/device-tree-xlnx
2) Go to the HSI prompt
[vabbarap@xhdl3763 /proj/xhdsswstaff/vabbarap/Overlay/New_hdf> % hsi
hsi v2017.3 (64-bit)SW Build 2018833 on Wed Oct 4 19:58:07 MDT 2017
Copyright 1986-2017 Xilinx, Inc. All Rights Reserved.
3)
hsi% open_hw_design system.hdf
4)
hsi% set_repo_path /home/vabbarap/workspace/sync_dt_tip/clk_wiz_15_12_2017 (DTG repo path)device-tree-xlnx
5)
hsi% create_sw_design -proc psu_cortexa53_0 sd22 -os device_tree
6)
hsi% set_property CONFIG.dt_overlay true [get_os]
7)
hsi% generate_target -dir dt/
hsi% ls dt/
pcw.dtsi pl.dtsi sd22.mss system-top.dts zynqmp-clk-ccf.dtsi zynqmp.dtsi
Using XSCT (From 2019.2 release no hsi support)
...
3) hsi open_hw_design system.xsa
4) hsi set_repo_path /home/vabbarap/workspace/sync_dt_tip/dt_15_12_2019 (DTG repo path)
5) hsi create_sw_design -proc psu_cortexa53_0 sd22 -os device_tree
6) hsi set_property CONFIG.dt_overlay true [hsi get_os]
6)hsi generate_target -dir dt
Customizing/Extending DTG for Custom Hardware and Drivers
This section is for users wising to extend DTG to accommodate their own custom hardware and drivers.
Relevant Files
Microprocessor software specification(MSS) file
The MSS file contains directives for customizing operating systems (OSs), libraries, and drivers.Microprocessor Driver Definition(MDD) file
An MDD file contains directives for customizing software drivers.Each device driver has an MDD file and a Tcl file associated with it. The MDD file is used by the Tcl file to customize the driver, depending on different options configured in the MSS file.
The driver source files and the MDD file for each driver must be located at specific directories in order to find the files and the drivers.
Driver Definition
Driver Definition involves defining a Data Definition file (MDD) and a Data Generation file (Tcl file).Data Definition File: The MDD file (<driver_name>.mdd) contains the configurable parameters.
Data Generation File: The second file (<driver_name>.tcl, with the filename being the same as the MDD filename) uses the parameters configured in the MSS file for the
driver to generate data.
How to add a new driver to the DTG
1. Sync the repo https://github.com/xilinx/device-tree-xlnx2. Create a folder with the driver name say for example axi_iic device-tree-xlnx/axi_iic/
3. Add the file data under axi_iic like device-tree-xlnx/axi_iic/data/
4. Create the files axi_iic.mdd and axi_iic.tcl under device-tree-xlnx/axi_iic/data/axi_iic.mdd axi_iic.tcl
5. The syntax for the file axi_iic.mdd is as
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
OPTION psf_version = 3.0; BEGIN driver axi_iic OPTION supported_peripherals = (axi_iic);--> the axi_iic is the IP_NAME which we get from the HDF file. OPTION supported_os_types = (DTS); OPTION driver_state = ACTIVE; OPTION NAME = axi_iic; END drive |
6. The syntax for the file axi_iic.tcl where you can have the properties which need to be set based on the some condition will be defined
We use HSI APIs to update the node properities. The below we update the clock property for axi_iic calling a generic function as below
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
io_bd_iic_0: i2c@a1200000 {
#address-cells = <1>;
#size-cells = <0>;
clock-names = "s_axi_aclk";
clocks = <&misc_clk_0>;
compatible = "xlnx,xps-iic-2.00.a";
interrupt-names = "iic2intc_irpt";
interrupt-parent = <&gic>;
interrupts = <0 2 4>;
reg = <0x0 0xa1200000 0x0 0x10000>;
}; |
For Custom IPs the DTG will generate the node with "compatible" property and interrupts if any connected.
;
}; |
Custom IPs:
For custom IPs DT node will contain the string "/* This is a place holder node for a custom IP, user may need to update the entries */"
Note |
---|
Custom IPs the DTG will not generate all the properties of the node, customer should add it manually to the respective node. It will only generate a node with compatible property, irqs & clocks if connected. |
Sugar syntax overlay support in DTG
Customer shouldCustomer should migrate the DTG dtsi files from fragment overlays to sugar syntax.
With sugar syntax, the syntax used by an overlay is now compatible with the syntax used by an
include file, if the include file uses labels as paths instead of using explicit paths.
Release Notes
- 2016.4 DTG Release Notes
- http://www.wiki.xilinx.com/2017.3+Linux+and+DTG+Release+Notes
- http://www.wiki.xilinx.com/2017.4+Linux+and+DTG+Release+Notes
- http://www.wiki.xilinx.com/2018.1+Linux+and+DTG+Release+Notes
- http://www.wiki.xilinx.com/2018.2+Linux+and+DTG+Release+Notes
- 2018.3 Release Notes for Open Source Components (see DTG section)
- 2022.1 Release Notes for Open Source Components (see DTG section)
Build Steps
- Build FSBL
- Build Device Tree Compiler (DTC)
- Build PMU Firmware
- Build Arm Trusted Firmware (ATF)
- Build U-Boot
- Build and Modify a Root File System
- (You are here) Build Device Tree Blob
- Build Linux Kernel
- Prepare Boot Image
- Prepare Boot Medium
- Setup a Serial Console
- Additional Information: Build Qt and Qwt Libraries
Related Links
- Build U-Boot
- Build Linux Kernel
- Updated device tree specification can be found here https://www.devicetree.org/
- https://elinux.org/Device_Tree_Usage