This is an old revision of the document!
===== Overview ===== Stuff related to device trees and the Linux kernel, using examples from the current Linux kernel. To do: * overlays ===== Some links ===== General links: * [[https://www.devicetree.org/|devicetree.org]] * [[http://developer.toradex.com/device-tree-customization|Toradex: Device tree customization]] * [[http://free-electrons.com/pub/conferences/2014/elc/petazzoni-device-tree-dummies/|Thomas Petazzoni's "Device Tree for Dummies"]] * [[https://www.nxp.com/docs/en/application-note/AN5125.pdf|NXP: Introduction to Device Trees]] * [[https://www.openfirmware.info/data/docs/of1275.pdf|IEEE 1275]] Kernel links: * [[https://github.com/torvalds/linux/tree/master/Documentation|Documentation/]] * [[https://github.com/torvalds/linux/tree/master/Documentation/devicetree|devicetree/]] * [[https://github.com/torvalds/linux/tree/master/include|include/]] * [[https://github.com/torvalds/linux/tree/master/include/dt-bindings|dt-bindings/]] * [[https://github.com/torvalds/linux/tree/master/drivers|drivers/]] * [[https://github.com/torvalds/linux/tree/master/drivers/of|of/]] elinux.org pages: * [[https://elinux.org/Device_Tree_Reference|Device Tree Reference]] * [[https://elinux.org/Device_Tree_Usage|Device Tree Usage]] * [[https://elinux.org/Device_Tree_Source_Undocumented|Device_Tree_Source_Undocumented]] * [[https://elinux.org/Device_Tree_Mysteries|Device_Tree_Mysteries]] Xillybus Zynq Device Tree Tutorial: * [[http://xillybus.com/tutorials/device-tree-zynq-1|Part 1]] * [[http://xillybus.com/tutorials/device-tree-zynq-2|Part 2]] * [[http://xillybus.com/tutorials/device-tree-zynq-3|Part 3]] * [[http://xillybus.com/tutorials/device-tree-zynq-4|Part 4]] * [[http://xillybus.com/tutorials/device-tree-zynq-5|Part 5]] * [[http://xillybus.com/tutorials/device-tree-altera-soc-cyclone|Setting up a device tree entry on Altera’s SoC FPGAs]] ===== Internal wiki pages ===== * [[Device tree naming conventions]] * [[Proper device tree design]] * [[Comparing device trees with dtx_diff]] ===== Proper device tree design ===== ==== Proper use of .dtsi files ==== There is **//no reason//** to make local copies of kernel-supplied ''.dtsi'' files and alter them; such files should be included as is, and //all// alterations should be made in the ''.dts'' file or a more general board-related ''.dtsi'' file supplied by that developer. Any alterations that involve actual //removal// of included content should be done via one of the two directives: * ''/delete-property/'' * ''/delete-node/'' This functionality was introduced into the Linux kernel file ''scripts/dtc/dtc-lexer.l'' file in Sept of 2012: <file> commit cd296721a9645f9f28800a072490fa15458d1fb7 Author: Stephen Warren <swarren@nvidia.com> Date: Fri Sep 28 21:25:59 2012 +0000 dtc: import latest upstream dtc This updates scripts/dtc to commit 317a5d9 "dtc: zero out new label objects" from git://git.jdl.com/software/dtc.git. This adds features such as: * /bits/ syntax for cell data. * Math expressions within cell data. * The ability to delete properties or nodes. * Support for #line directives in the input file, which allows the use of cpp on *.dts. * -i command-line option (/include/ path) * -W/-E command-line options for error/warning control. * Removal of spew to STDOUT containing the filename being compiled. * Many additions to the libfdt API. Signed-off-by: Stephen Warren <swarren@nvidia.com> Acked-by: Jon Loeliger <jdl@jdl.com> Signed-off-by: Rob Herring <rob.herring@calxeda.com> </file> Examples can be seen [[https://elinux.org/Device_Tree_Source_Undocumented|here]]. ==== Examples of /delete-node/ ==== === imx6dl-tx6s-8034.dts === <file> #include "imx6dl.dtsi" #include "imx6qdl-tx6.dtsi" / { model = "Ka-Ro electronics TX6S-8034 Module"; compatible = "karo,imx6dl-tx6dl", "fsl,imx6dl"; aliases { display = &display; ipu1 = &ipu1; }; cpus { /delete-node/ cpu@1; }; </file> === imx6q-utilite-pro.dts === <file> #include <dt-bindings/input/input.h> #include "imx6q-cm-fx6.dts" / { model = "CompuLab Utilite Pro"; compatible = "compulab,utilite-pro", "compulab,cm-fx6", "fsl,imx6q"; ... }; /* * A single IPU is not able to drive both display interfaces available on the * Utilite Pro at high resolution due to its bandwidth limitation. Since the * tfp410 encoder is wired up to IPU1, sever the link between IPU1 and the * SoC-internal Designware HDMI encoder forcing the latter to be connected to * IPU2 instead of IPU1. */ /delete-node/&ipu1_di0_hdmi; /delete-node/&hdmi_mux_0; /delete-node/&ipu1_di1_hdmi; /delete-node/&hdmi_mux_1; </file> ==== Examples of /delete-property/ ==== === imx6qp.dtsi === <file> #include "imx6q.dtsi" / { soc { ... }; &fec { /delete-property/interrupts-extended; interrupts = <0 118 IRQ_TYPE_LEVEL_HIGH>, <0 119 IRQ_TYPE_LEVEL_HIGH>; }; </file> === imx6ul-tx6ul-mainboard.dts === <file> #include "imx6ul.dtsi" #include "imx6ul-tx6ul.dtsi" / { model = "Ka-Ro electronics TXUL-0010 Module on TXUL Mainboard"; compatible = "karo,imx6ul-tx6ul", "fsl,imx6ul"; aliases { lcdif_24bit_pins_a = &pinctrl_disp0_3; mmc0 = &usdhc1; /delete-property/ mmc1; serial2 = &uart3; serial4 = &uart5; }; /delete-node/ sound; }; ... &usdhc1 { pinctrl-0 = <&pinctrl_usdhc1>; non-removable; /delete-property/ cd-gpios; cap-sdio-irq; }; &uart1 { pinctrl-0 = <&pinctrl_uart1>; /delete-property/ uart-has-rtscts; }; &uart2 { pinctrl-0 = <&pinctrl_uart2>; /delete-property/ uart-has-rtscts; status = "okay"; }; </file>
