doc: bindings: Add description for MDIO MUX dts nodes

Adds a short bindings document describing the expected structure of a MDIO
MUX dts node.  This is based on Linux binding and the example is in fact
copied from there.

Signed-off-by: Alex Marginean <alexm.osslist@gmail.com>
Acked-by: Joe Hershberger <joe.hershberger@ni.com>
Reviewed-by: Bin Meng <bmeng.cn@gmail.com>

diff --git a/doc/device-tree-bindings/net/mdio-mux.txt b/doc/device-tree-bindings/net/mdio-mux.txt
new file mode 100644 (file)
index 0000000..eaa31ef
--- /dev/null
+++ b/doc/device-tree-bindings/net/mdio-mux.txt
@@ -0,0 +1,138 @@
+The expected structure of an MDIO MUX device tree node is described here.  This
+is heavily based on current Linux specification.
+One notable difference to Linux is that mdio-parent-bus is currently required
+by U-Boot, not optional as is in Linux.  Current U-Boot MDIO MUX udevice class
+implementation does not have specific support for MDIOs with an integrated MUX,
+the property should be made optional if such support is added.
+
+The MDIO buses downstream of the MUX should be described in the device tree as
+child nodes as indicated below.
+
+Required properties:
+mdio-parent-bus = a phandle to the MDIO bus used to perform actual I/O.  This is
+                  typically a real MDIO device, unless there are cascaded MUXes.
+#address-cells = <1>, each MDIO group is identified by one 32b value.
+#size-cells = <0>
+
+Other properties:
+The properties described here are sufficient for MDIO MUX DM class code, but
+MUX drivers may define additional properties, either required or optional.
+
+Required properties in child nodes:
+reg = value to be configured on the MUX to select the respective downstream
+      MDIO.
+
+Child nodes should normally contain PHY nodes, referenced by phandle from
+ethernet nodes of the eth interfaces using these PHYs.
+
+Example structure, extracted from Linux bindings document:
+
+       /* The parent MDIO bus. */
+       smi1: mdio@1180000001900 {
+               compatible = "cavium,octeon-3860-mdio";
+               #address-cells = <1>;
+               #size-cells = <0>;
+               reg = <0x11800 0x00001900 0x0 0x40>;
+       };
+       /*
+        * An NXP sn74cbtlv3253 dual 1-of-4 switch controlled by a
+        * pair of GPIO lines.  Child busses 2 and 3 populated with 4
+        * PHYs each.
+        */
+       mdio-mux {
+               compatible = "mdio-mux-gpio";
+               gpios = <&gpio1 3 0>, <&gpio1 4 0>;
+               mdio-parent-bus = <&smi1>;
+               #address-cells = <1>;
+               #size-cells = <0>;
+               mdio@2 {
+                       reg = <2>;
+                       #address-cells = <1>;
+                       #size-cells = <0>;
+                       phy11: ethernet-phy@1 {
+                               reg = <1>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <10 8>; /* Pin 10, active low */
+                       };
+                       phy12: ethernet-phy@2 {
+                               reg = <2>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <10 8>; /* Pin 10, active low */
+                       };
+                       phy13: ethernet-phy@3 {
+                               reg = <3>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <10 8>; /* Pin 10, active low */
+                       };
+                       phy14: ethernet-phy@4 {
+                               reg = <4>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <10 8>; /* Pin 10, active low */
+                       };
+               };
+               mdio@3 {
+                       reg = <3>;
+                       #address-cells = <1>;
+                       #size-cells = <0>;
+                       phy21: ethernet-phy@1 {
+                               reg = <1>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <12 8>; /* Pin 12, active low */
+                       };
+                       phy22: ethernet-phy@2 {
+                               reg = <2>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <12 8>; /* Pin 12, active low */
+                       };
+                       phy23: ethernet-phy@3 {
+                               reg = <3>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <12 8>; /* Pin 12, active low */
+                       };
+                       phy24: ethernet-phy@4 {
+                               reg = <4>;
+                               compatible = "marvell,88e1149r";
+                               marvell,reg-init = <3 0x10 0 0x5777>,
+                                       <3 0x11 0 0x00aa>,
+                                       <3 0x12 0 0x4105>,
+                                       <3 0x13 0 0x0a60>;
+                               interrupt-parent = <&gpio>;
+                               interrupts = <12 8>; /* Pin 12, active low */
+                       };
+               };
+       };