[net-next RFC PATCH v2 02/11] dt-bindings: net: document ethernet PHY package nodes

[Andrew Lunn]

On Sat, Nov 25, 2023 at 01:11:18AM +0100, Christian Marangi wrote:
> Document ethernet PHY package nodes used to describe PHY shipped in
> bundle of 4-5 PHY. These particular PHY require specific PHY in the
> package for global onfiguration of the PHY package.

I would not say that is true. We have been able to handle such PHYs
without a problem so far. This binding is not about a collection of
PHYs in one package with shared registers. Its about DT properties
which are shared across the package.

This binding is simply a container. It contains properties shared by
all PHYs in the container, and it contains the PHYs itself. The
properties should be described in another DT scheme, selected by a
compatible for the PHY package. The PHYs themselves a follow the
standard ethernet-phy scheme.

I would also add a comment about the reg value in the PHY properties
being absolute, not relative. You can make this clearer in the
example, by using a base address of 16, and PHYs 16 and 20.

Please include this is in the binding itself, as part of the
documentation.

> +properties:
> +  $nodename:
> +    pattern: "^ethernet-phy-package(@[a-f0-9]+)?$"
> +
> +  reg:
> +    minimum: 0
> +    maximum: 31
> +    description:
> +      The ID number for the PHY.
> +
> +  '#address-cells':
> +    const: 1
> +
> +  '#size-cells':
> +    const: 0
> +
> +patternProperties:
> +  ^ethernet-phy(@[a-f0-9]+)?$:
> +    $ref: /schemas/net/ethernet-phy.yaml#
> +
> +required:
> +  - reg

A compatible is required.

> +examples:
> +  - |
> +    mdio {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ethernet-phy-package at 0 {

A compatible is needed here.

> +            #address-cells = <1>;
> +            #size-cells = <0>;
> +            reg = <0>;
> +
> +            ethernet-phy at 0 {
> +              compatible = "ethernet-phy-ieee802.3-c22";

This compatible is optional, and c22 is the default, so i would not
list it.

     Andrew