[v2,net-next/devicetree,3/5] dt-bindings: net: dsa: ocelot: document the vsc9959 core

From: Vladimir Oltean <vladimir.oltean@nxp.com>

This patch adds the required documentation for the embedded L2 switch
inside the NXP LS1028A chip.

I've submitted it in the legacy format instead of yaml schema, because
DSA itself has not yet been converted to yaml, and this driver defines
no custom bindings.

Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
---
Changes in v2:
Adapted phy-mode = "gmii" to phy-mode = "internal".

 .../devicetree/bindings/net/dsa/ocelot.txt    | 96 +++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/net/dsa/ocelot.txt

On Wed, Feb 19, 2020 at 05:12:57PM +0200, Vladimir Oltean wrote:
> From: Vladimir Oltean <vladimir.oltean@nxp.com>
> 
> This patch adds the required documentation for the embedded L2 switch
> inside the NXP LS1028A chip.
> 
> I've submitted it in the legacy format instead of yaml schema, because
> DSA itself has not yet been converted to yaml, and this driver defines
> no custom bindings.
> 
> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

> This patch adds the required documentation for the embedded L2 switch
> inside the NXP LS1028A chip.
> 
> I've submitted it in the legacy format instead of yaml schema, because
> DSA itself has not yet been converted to yaml, and this driver defines
> no custom bindings.
> 
> Signed-off-by: Vladimir Oltean <vladimir.oltean@nxp.com>
> ---
> Changes in v2:
> Adapted phy-mode = "gmii" to phy-mode = "internal".
> 
>  .../devicetree/bindings/net/dsa/ocelot.txt    | 96 +++++++++++++++++++
>  1 file changed, 96 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/net/dsa/ocelot.txt
> 
> diff --git a/Documentation/devicetree/bindings/net/dsa/ocelot.txt b/Documentation/devicetree/bindings/net/dsa/ocelot.txt
> new file mode 100644
> index 000000000000..a9d86e09dafa
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/dsa/ocelot.txt
> @@ -0,0 +1,96 @@
> +Microchip Ocelot switch driver family
> +=====================================
> +
> +Felix
> +-----
> +
> +The VSC9959 core is currently the only switch supported by the driver, and is
> +found in the NXP LS1028A. It is a PCI device, part of the larger ENETC root
> +complex. As a result, the ethernet-switch node is a sub-node of the PCIe root
> +complex node and its "reg" property conforms to the parent node bindings:
> +
> +* reg: Specifies PCIe Device Number and Function Number of the endpoint device,
> +  in this case for the Ethernet L2Switch it is PF5 (of device 0, bus 0).
> +
> +It does not require a "compatible" string.
> +
> +The interrupt line is used to signal availability of PTP TX timestamps and for
> +TSN frame preemption.
> +
> +For the external switch ports, depending on board configuration, "phy-mode" and
> +"phy-handle" are populated by board specific device tree instances. Ports 4 and
> +5 are fixed as internal ports in the NXP LS1028A instantiation.
> +
> +Any port can be disabled, but the CPU port should be kept enabled.

What is the reason for this? Do you mean if you actually want to use it? In
fact, I'd would like to see it disabled by default in the .dtsi file. It
doesn't make sense to just have the CPU port enabled, but not any of the
outgoing ports. It'd just confuse the user if there is an additional
network port which cannot be used.

-michael

> +
> +The CPU port property ("ethernet"), which is assigned by default to the 2.5Gbps
> +port@4, can be moved to the 1Gbps port@5, depending on the specific use case.
> +DSA tagging is supported on a single port at a time.
> +
> +For the rest of the device tree binding definitions, which are standard DSA and
> +PCI, refer to the following documents:
> +
> +Documentation/devicetree/bindings/net/dsa/dsa.txt
> +Documentation/devicetree/bindings/pci/pci.txt
> +
> +Example:
> +
> +&soc {
> +	pcie@1f0000000 { /* Integrated Endpoint Root Complex */
> +		ethernet-switch@0,5 {
> +			reg = <0x000500 0 0 0 0>;
> +			/* IEP INT_B */
> +			interrupts = <GIC_SPI 95 IRQ_TYPE_LEVEL_HIGH>;
> +
> +			ports {
> +				#address-cells = <1>;
> +				#size-cells = <0>;
> +
> +				/* External ports */
> +				port@0 {
> +					reg = <0>;
> +					label = "swp0";
> +				};
> +
> +				port@1 {
> +					reg = <1>;
> +					label = "swp1";
> +				};
> +
> +				port@2 {
> +					reg = <2>;
> +					label = "swp2";
> +				};
> +
> +				port@3 {
> +					reg = <3>;
> +					label = "swp3";
> +				};
> +
> +				/* Tagging CPU port */
> +				port@4 {
> +					reg = <4>;
> +					ethernet = <&enetc_port2>;
> +					phy-mode = "internal";
> +
> +					fixed-link {
> +						speed = <2500>;
> +						full-duplex;
> +					};
> +				};
> +
> +				/* Non-tagging CPU port */
> +				port@5 {
> +					reg = <5>;
> +					phy-mode = "internal";
> +					status = "disabled";
> +
> +					fixed-link {
> +						speed = <1000>;
> +						full-duplex;
> +					};
> +				};
> +			};
> +		};
> +	};
> +};
> -- 
> 2.17.1

Hi Michael,

On Sat, 22 Feb 2020 at 13:28, Michael Walle <michael@walle.cc> wrote:
>
> > +Any port can be disabled, but the CPU port should be kept enabled.
>
> What is the reason for this? Do you mean if you actually want to use it? In
> fact, I'd would like to see it disabled by default in the .dtsi file. It
> doesn't make sense to just have the CPU port enabled, but not any of the
> outgoing ports. It'd just confuse the user if there is an additional
> network port which cannot be used.
>
> -michael
>

I can disable all internal ports by default, but there is one
configuration which will not work: enabling only eno3 and switch port
5. This is because the switch PCS registers belong to eno2, and if
that is disabled, the memory accesses will be invalid. So providing a
configuration with eno2 disabled by default is more likely to produce
confusion. But I'll try to clarify better next time.

> > --
> > 2.17.1
>
>

Thanks,
-Vladimir