Re: [PATCH 2/8] dt-bindings: net: Add a YAML schemas for the generic PHY options

[Rob Herring <robh+dt@xxxxxxxxxx>]

On Thu, May 23, 2019 at 4:57 AM Maxime Ripard <maxime.ripard@xxxxxxxxxxx> wrote:
>
> The networking PHYs have a number of available device tree properties that
> can be used in their device tree node. Add a YAML schemas for those.
>
> Signed-off-by: Maxime Ripard <maxime.ripard@xxxxxxxxxxx>
> ---
>  Documentation/devicetree/bindings/net/ethernet-phy.yaml | 148 +++++++++-
>  Documentation/devicetree/bindings/net/phy.txt           |  80 +-----
>  2 files changed, 149 insertions(+), 79 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/net/ethernet-phy.yaml
>
> diff --git a/Documentation/devicetree/bindings/net/ethernet-phy.yaml b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> new file mode 100644
> index 000000000000..eb79ee6db977
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/ethernet-phy.yaml
> @@ -0,0 +1,148 @@
> +# SPDX-License-Identifier: GPL-2.0
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/ethernet-phy.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Ethernet PHY Generic Binding
> +
> +maintainers:
> +  - David S. Miller <davem@xxxxxxxxxxxxx>
> +
> +properties:
> +  $nodename:
> +    pattern: "^ethernet-phy(@[a-f0-9])?$"
> +
> +  compatible:
> +    oneOf:
> +      - const: ethernet-phy-ieee802.3-c22
> +        description: PHYs that implement IEEE802.3 clause 22
> +      - const: ethernet-phy-ieee802.3-c45
> +        description: PHYs that implement IEEE802.3 clause 45
> +      - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
> +        description:
> +          The first group of digits is the 16 bit Phy Identifier 1
> +          register, this is the chip vendor OUI bits 3:18. The
> +          second group of digits is the Phy Identifier 2 register,
> +          this is the chip vendor OUI bits 19:24, followed by 10
> +          bits of a vendor specific ID.
> +
> +  reg:
> +    maxItems: 1
> +    minimum: 0
> +    maximum: 31

min/max need to be under 'items'. I don't think these would ever be
valid if the type is an array.

I've modified the meta-schema to catch this.

> +    description:
> +      The ID number for the PHY.
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  max-speed:
> +    enum:
> +      - 10
> +      - 100
> +      - 1000
> +    description:
> +      Maximum PHY supported speed in Mbits / seconds.
> +
> +  broken-turn-around:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      If set, indicates the PHY device does not correctly release
> +      the turn around line low at the end of a MDIO transaction.
> +
> +  enet-phy-lane-swap:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      If set, indicates the PHY will swap the TX/RX lanes to
> +      compensate for the board being designed with the lanes
> +      swapped.
> +
> +  eee-broken-100tx:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  eee-broken-1000t:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  eee-broken-10gt:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  eee-broken-1000kx:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  eee-broken-10gkx4:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  eee-broken-10gkr:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      Mark the corresponding energy efficient ethernet mode as
> +      broken and request the ethernet to stop advertising it.
> +
> +  phy-is-integrated:
> +    $ref: /schemas/types.yaml#definitions/flag
> +    description:
> +      If set, indicates that the PHY is integrated into the same
> +      physical package as the Ethernet MAC. If needed, muxers
> +      should be configured to ensure the integrated PHY is
> +      used. The absence of this property indicates the muxers
> +      should be configured so that the external PHY is used.
> +
> +  resets:
> +    maxItems: 1
> +
> +  reset-names:
> +    const: phy
> +
> +  reset-gpios:
> +    description:
> +      The GPIO phandle and specifier for the PHY reset signal.

maxItems: 1

I have a meta-schema change to catch this, but It will require updates
to some existing cases.


> +
> +  reset-assert-us:
> +    description:
> +      Delay after the reset was asserted in microseconds. If this
> +      property is missing the delay will be skipped.
> +
> +  reset-deassert-us:
> +    description:
> +      Delay after the reset was deasserted in microseconds. If
> +      this property is missing the delay will be skipped.
> +
> +required:
> +  - reg
> +  - interrupts
> +
> +examples:
> +  - |
> +    ethernet {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        ethernet-phy@0 {
> +            compatible = "ethernet-phy-id0141.0e90", "ethernet-phy-ieee802.3-c22";
> +            interrupt-parent = <&PIC>;
> +            interrupts = <35 1>;
> +            reg = <0>;
> +
> +            resets = <&rst 8>;
> +            reset-names = "phy";
> +            reset-gpios = <&gpio1 4 1>;
> +            reset-assert-us = <1000>;
> +            reset-deassert-us = <2000>;
> +        };
> +    };