===== Overview =====

Proper ''.dts'' file design.

===== One board, one .dts file =====

Every distinct board merits its own ''.dts'' file, as in:

  * ''am335x-boneblack.dts''
  * ''am335x-boneblack-wireless.dts''
  * ''am335x-boneblue.dts''
  * ''am335x-bone.dts''
  * ''am335x-bonegreen.dts''
  * ''am335x-bonegreen-wireless.dts''

===== 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>

==== imx6ulz.dtsi ====

<code>
#include "imx6ull.dtsi"

/ {
        aliases {
                /delete-property/ ethernet0;
                /delete-property/ ethernet1;
                /delete-property/ i2c2;
                /delete-property/ i2c3;
                /delete-property/ serial4;
                /delete-property/ serial5;
                /delete-property/ serial6;
                /delete-property/ serial7;
                /delete-property/ spi2;
                /delete-property/ spi3;
        };
};

/delete-node/ &adc1;
/delete-node/ &can1;
/delete-node/ &can2;
/delete-node/ &ecspi3;
/delete-node/ &ecspi4;
/delete-node/ &epit2;
/delete-node/ &gpt2;
/delete-node/ &i2c3;
/delete-node/ &i2c4;
/delete-node/ &pwm5;
/delete-node/ &pwm6;
/delete-node/ &pwm7;
/delete-node/ &pwm8;
/delete-node/ &uart5;
/delete-node/ &uart6;
/delete-node/ &uart7;
/delete-node/ &uart8;
</code>