[U-Boot] [PATCH 2/4 v3] doc: bindings: Add description for MDIO MUX dts nodes

[Alex Marginean <alexm.osslist@gmail.com>]

On 7/8/2019 10:40 AM, Bin Meng wrote:
> On Tue, Jun 18, 2019 at 10:58 PM Alexandru Marginean
> <alexandru.marginean@nxp.com> wrote:
>>
>> 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>
>> ---
>>
>> Changes in v2:
>>          - no change
>> Changes in v3:
>>          - no change, just fighting with the email server
>>
>>   doc/device-tree-bindings/net/mdio-mux.txt | 61 +++++++++++++++++++++++
>>   1 file changed, 61 insertions(+)
>>   create mode 100644 doc/device-tree-bindings/net/mdio-mux.txt
>>
>> diff --git a/doc/device-tree-bindings/net/mdio-mux.txt b/doc/device-tree-bindings/net/mdio-mux.txt
>> new file mode 100644
>> index 0000000000..fdf817fd93
>> --- /dev/null
>> +++ b/doc/device-tree-bindings/net/mdio-mux.txt
>> @@ -0,0 +1,61 @@
>> +The expected structure of an MDIO MUX device tree node is described here.  This
>> +is heavily based on current Linux specification.
>> +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.
> 
> In Linux, "mdio-parent-bus" is optional, but in U-Boot this is required?

That was my plan, making it optional requires some extra code that I
didn't put in.  I could put that code in but it would be unused for now.
I can do it, or the change can be done whenever someone adds a MUX which
is driven over parent MDIO.

>> +#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 at 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.
>> +        */
> 
> It looks the example is not complete, which makes it hard for people
> to understand (ie: only bus 2 is listed below) without reading the
> Linux bindings doc.

I did chop it down to the piece I though it's relevant, I can pull in
the full example.  Or I can replace it with the definition of the device
I'm working on, that way the example is practical.  'mdio-mux-gpio' is
not something I was planning to add to u-boot now.

Thank you!
Alex

> 
>> +       mdio-mux {
>> +               compatible = "mdio-mux-gpio";
>> +               gpios = <&gpio1 3 0>, <&gpio1 4 0>;
>> +               mdio-parent-bus = <&smi1>;
>> +               #address-cells = <1>;
>> +               #size-cells = <0>;
>> +
>> +               mdio at 2 {
>> +                       reg = <2>;
>> +                       #address-cells = <1>;
>> +                       #size-cells = <0>;
>> +
>> +                       phy11: ethernet-phy at 1 {
>> +                               reg = <1>;
>> +                               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 */
>> +                       };
>> +               };
>> +       };
>> +
> 
> Regards,
> Bin
> _______________________________________________
> U-Boot mailing list
> U-Boot at lists.denx.de
> https://lists.denx.de/listinfo/u-boot
>