Devicetree bindings serve as a guide on how to create a node for a given peripheral. They are standardized node formats that are specific to the hardware that they represent. A devicetree binding specifies how to name a node and properties that a peripheral's node requires. They are required when drivers are submitted to upstream maintainers to be included in projects like U-Boot and Linux. These files also often have example nodes. Other devicetrees that use the same drivers will also be great examples for how to properly create a new node for a given peripheral.

Devicetree bindings are found in the Linux kernel documentation in TI_LINUX/Documentation/devicetree/bindings/. U-Boot provides bindings for some nodes as well. These are found in TI_U_BOOT/include/dt-bindings/. Since the board devicetrees in U-Boot and the Linux kernel are the same, it is helpful to consult both sources to construct peripheral nodes. Relevant bindings files are located by using a grep search on the compatible string associated with the node, property names, and property settings. More guidance on using the devicetree bindings is in the Bootlin devicetree training in Section 10.

The first step to configuring a node is to check the SoC devicetree definition of the node. Nodes in SoC devicetrees contain most of the configuration settings required for the peripheral, but they are disabled since they are incomplete. The nodes are modified to match a board's hardware configuration and enabled in the board devicetree file, in this case k3-am625-<boardname>.dts. It may be helpful to refer back to the AM62x Devicetree diagram to understand how the board DTS files and the SoC DTSI files interact. Nodes often reference other nodes located throughout included devicetree files. To enable a node, ensure its referenced dependencies are also enabled. Working through the following Ethernet example should help make this more clear.

Cpsw3g, an Ethernet MAC, operates in the main domain. This indicates the SoC devicetree node definition is in k3-am62-main.dtsi. This node references other nodes, such as &k3_clks, &main_pktdma, and &phy_gmii_sel. It is necessary to ensure these nodes are enabled by the board devicetree. A node is enabled by setting the "status" property, as seen below.

+ &cpsw3g {
+    status = "okay";
+ };

In addition to being enabled, every peripheral that is configured needs to have its pinctrl property set to the correct pin configuration that was pasted into k3-am625-<boardname>.dts. Refer to Section 4.4 to make this modification. After following these steps, the pin configuration properties are set below.

&cpsw3g {
     status = "okay";
     pinctrl-names = "default";
     pinctrl-0 = <rgmii1-custom_pins_default>;
};

For guidance on which pin configurations to include for a given peripheral, refer to the peripheral's configuration in k3-am625-sk.dts and k3-am62x-sk-common.dtsi.

The property "pinctrl-names" is added and set to "default" to specify the added pin configuration to always be used. Some configurations may require multiple pin configurations. For a complete guide to configuring pin settings, see TI_LINUX/Documentation/devicetree/bindings/pinctrl/pinctrl-bindings.txt.