dt-bindings: net: Add a YAML schemas for the generic PHY options

# 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:

  - Andrew Lunn <andrew@lunn.ch>

  - Florian Fainelli <f.fainelli@gmail.com>

  - Heiner Kallweit <hkallweit1@gmail.com>

# The dt-schema tools will generate a select statement first by using

# the compatible, and second by using the node name if any. In our

# case, the node name is the one we want to match on, while the

# compatible is optional.

select:

  properties:

    $nodename:

      pattern: "^ethernet-phy(@[a-f0-9]+)?$"

  required:

    - $nodename

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:

          If the PHY reports an incorrect ID (or none at all) then the

          compatible list may contain an entry with the correct PHY ID

          in the above form.

          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.

      - items:

          - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"

          - const: ethernet-phy-ieee802.3-c45

  reg:

    minimum: 0

    maximum: 31

    description:

      The ID number for the PHY.

  interrupts:

    maxItems: 1

  max-speed:

    enum:

      - 10

      - 100

      - 1000

      - 2500

      - 5000

      - 10000

      - 20000

      - 25000

      - 40000

      - 50000

      - 56000

      - 100000

      - 200000

    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:

    maxItems: 1

    description:

      The GPIO phandle and specifier for the PHY reset signal.

  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-c45";

            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>;

        };

    };

PHY nodes

Required properties:

 - interrupts : interrupt specifier for the sole interrupt.

 - reg : The ID number for the phy, usually a small integer

Optional Properties:

- compatible: Compatible list, may contain

  "ethernet-phy-ieee802.3-c22" or "ethernet-phy-ieee802.3-c45" for

  PHYs that implement IEEE802.3 clause 22 or IEEE802.3 clause 45

  specifications. If neither of these are specified, the default is to

  assume clause 22.

  If the PHY reports an incorrect ID (or none at all) then the

  "compatible" list may contain an entry with the correct PHY ID in the

  form: "ethernet-phy-idAAAA.BBBB" where

     AAAA - The value of the 16 bit Phy Identifier 1 register as

            4 hex digits. This is the chip vendor OUI bits 3:18

     BBBB - The value of the 16 bit Phy Identifier 2 register as

            4 hex digits. This is the chip vendor OUI bits 19:24,

            followed by 10 bits of a vendor specific ID.

  The compatible list should not contain other values than those

  listed here.

- max-speed: Maximum PHY supported speed (10, 100, 1000...)

- broken-turn-around: 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: If set, indicates the PHY will swap the TX/RX lanes to

  compensate for the board being designed with the lanes swapped.

- enet-phy-lane-no-swap: If set, indicates that PHY will disable swap of the

  TX/RX lanes. This property allows the PHY to work correcly after e.g. wrong

  bootstrap configuration caused by issues in PCB layout design.

- eee-broken-100tx:

- eee-broken-1000t:

- eee-broken-10gt:

- eee-broken-1000kx:

- eee-broken-10gkx4:

- eee-broken-10gkr:

  Mark the corresponding energy efficient ethernet mode as broken and

  request the ethernet to stop advertising it.

- phy-is-integrated: 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: The reset-controller phandle and specifier for the PHY reset signal.

- reset-names: Must be "phy" for the PHY reset signal.

- reset-gpios: The GPIO phandle and specifier for the PHY reset signal.

- reset-assert-us: Delay after the reset was asserted in microseconds.

  If this property is missing the delay will be skipped.

- reset-deassert-us: Delay after the reset was deasserted in microseconds.

  If this property is missing the delay will be skipped.

Example:

ethernet-phy@0 {

	compatible = "ethernet-phy-id0141.0e90", "ethernet-phy-ieee802.3-c22";

	interrupt-parent = <&PIC>;

	interrupts = <35 IRQ_TYPE_EDGE_RISING>;

	reg = <0>;

	resets = <&rst 8>;

	reset-names = "phy";

	reset-gpios = <&gpio1 4 GPIO_ACTIVE_LOW>;

	reset-assert-us = <1000>;

	reset-deassert-us = <2000>;

};

This file has moved to ethernet-phy.yaml.