A useful tool to help understand devicetree structure is reverse compiling the devicetree binary (DTB) that results from the build process. This results in a readable file that contains all nodes across the devicetrees included in the compilation process. The resulting file makes it easy to see all nodes and properties describing the peripherals. The DTB is found at OUTPUT_DIR/a53/k3-am625-<boardname>.dtb. To reverse compile the DTB, use the command below:

$ dtc -I dtb -O dts k3-am625-<boardname>.dtb -o <boardname>-reversed.dts

The reverse compiled DTB is the file <boardname>-reversed.dts. This output can be compared to the examples in the bindings files and other DTS files for completeness and correctness.

Another great resource to build a devicetree is to use other devicetrees as a guide to initialize peripherals. By compiling another devicetree, such as k3-am625-sk.dts, and reverse compiling the resulting DTB, it is easy to see other node configurations for peripherals. In general, the EVM devicetree nodes can be used as a good reference to represent a custom board's peripherals. If the use of a peripheral is similar to the EVM, only minor modifications may be needed, if any.

A good method for devicetree development on a custom board is to search the EVM devicetree files, k3-am62x-sk-common.dtsi and k3-am625-sk.dts, to see what properties are applied on top of the SoC definition of the node. These properties usually need to be set in the custom board's devicetree as well. Searching in the devicetree bindings directory for properties and compatible strings leads to documentation on what each property defines and how it can be set.

In k3-am625-sk.dts, the Ethernet PHYs are defined as child nodes of the MDIO bus node. This is added to the board devicetree below. Assume the pin configuration and the status properties have already been set.

cpsw3g_mdio {
     status = "okay";
     pinctrl-names = "default";
     pinctrl-0 = <mdio-custom_pins_default>;
+        cpsw3g_phy0: ethernet-phy@0 {
+        };
};

In k3-am625-sk.dts, there are properties defined in the Ethernet PHY nodes. A grep search on any of these properties from the kernel bindings directory points us to ti,dp83867.txt, which indicates that there are four required properties for the PHY nodes. These are the same properties specified in the EVM board devicetree. This document also points us to a header file with different settings for these properties, which are control registers for the Ethernet PHY. These settings can be set based on the EVM devicetree settings, or by referencing the Ethernet port design documentation for device specifications. These values and the method of incorporation in the devicetree will change if different PHYs are used. This is seen below:

cpsw3g_mdio {
     status = "okay";
     pinctrl-names = "default";
     pinctrl-0 = <mdio-custom_pins_default>;
          cpsw3g_phy0: ethernet-phy@0 {
+              reg = <0>;
+              ti,rx-internal-delay = <DP83867_RGMIIDCTL_2_25_NS>;
+              ti,tx-internal-delay = <DP83867_RGMIIDCTL_2_75_NS>;
+              ti,fifo-depth = <DP83867_PHYCR_FIFO_DEPTH_4_B_NIB>;
+         };
};

The EVM devicetree adds the "phy-handle" property for &cpsw_port1, which assigns the PHY node to the port node. This property can be set below after enabling the node.

+ &cpsw_port1 {
+     status = "okay";
+     phy-handle = <&cpsw3g_phy0>;
+ };