Documentation/devicetree/bindings/net/ethernet-phy.yaml

# 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 Common Properties

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:
          PHYs contain identification registers. These will be read to
          identify the PHY. If the PHY reports an incorrect ID, or the
          PHY requires a specific initialization sequence (like a
          particular order of clocks, resets, power supplies), in
          order to be able to read the ID registers, then the
          compatible list must 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-c22
      - 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.

  phy-10base-t1l-2.4vpp:
    description: |
      tristate, request/disable 2.4 Vpp operating mode. The values are:
      0: Disable 2.4 Vpp operating mode.
      1: Request 2.4 Vpp operating mode from link partner.
      Absence of this property will leave configuration to default values.
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]

  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 end of the control phase of the
      MDIO transaction.

  brr-mode:
    $ref: /schemas/types.yaml#/definitions/flag
    description:
      If set, indicates the network cable interface is an alternative one as
      defined in the BroadR-Reach link mode specification under 1BR-100 and
      1BR-10 names. The PHY must be configured to operate in BroadR-Reach mode
      by software.

  clocks:
    minItems: 1
    maxItems: 2
    description:
      External clock connected to the PHY or RX and TX clocks that the PHY
      requires to enable explicitly. If not specified it is assumed
      that the PHY uses a fixed crystal or an internal oscillator or that the
      RX/TX clocks are hardware enabled by default.

  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.

  enet-phy-lane-no-swap:
    $ref: /schemas/types.yaml#/definitions/flag
    description:
      If set, indicates that PHY will disable swap of the
      TX/RX lanes. This property allows the PHY to work correctly after
      e.g. wrong bootstrap configuration caused by issues in PCB
      layout design.

  enet-phy-pair-order:
    $ref: /schemas/types.yaml#/definitions/uint32
    enum: [0, 1]
    description:
      For normal (0) or reverse (1) order of the pairs (ABCD -> DCBA).

  enet-phy-pair-polarity:
    $ref: /schemas/types.yaml#/definitions/uint32
    maximum: 0xf
    description:
      A bitmap to describe pair polarity swap. Bit 0 to swap polarity of pair A,
      bit 1 to swap polarity of pair B, bit 2 to swap polarity of pair C and bit
      3 to swap polarity of pair D.

  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.

  timing-role:
    $ref: /schemas/types.yaml#/definitions/string
    enum:
      - forced-master
      - forced-slave
      - preferred-master
      - preferred-slave
    description: |
      Specifies the timing role of the PHY in the network link. This property is
      required for setups where the role must be explicitly assigned via the
      device tree due to limitations in hardware strapping or incorrect strap
      configurations.
      It is applicable to Single Pair Ethernet (1000/100/10Base-T1) and other
      PHY types, including 1000Base-T, where it controls whether the PHY should
      be a master (clock source) or a slave (clock receiver).

      - 'forced-master': The PHY is forced to operate as a master.
      - 'forced-slave': The PHY is forced to operate as a slave.
      - 'preferred-master': Prefer the PHY to be master but allow negotiation.
      - 'preferred-slave': Prefer the PHY to be slave but allow negotiation.

  pses:
    $ref: /schemas/types.yaml#/definitions/phandle-array
    maxItems: 1
    description:
      Specifies a reference to a node representing a Power Sourcing Equipment.

  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.

  sfp:
    $ref: /schemas/types.yaml#/definitions/phandle
    description:
      Specifies a reference to a node representing a SFP cage.

  rx-internal-delay-ps:
    description: |
      RGMII Receive PHY Clock Delay defined in pico seconds.  This is used for
      PHY's that have configurable RX internal delays.  If this property is
      present then the PHY applies the RX delay.

  tx-internal-delay-ps:
    description: |
      RGMII Transmit PHY Clock Delay defined in pico seconds.  This is used for
      PHY's that have configurable TX internal delays. If this property is
      present then the PHY applies the TX delay.

  tx-amplitude-100base-tx-percent:
    description:
      Transmit amplitude gain applied for 100BASE-TX. 100% matches 2V
      peak-to-peak specified in ANSI X3.263. When omitted, the PHYs default
      will be left as is.

  mac-termination-ohms:
    maximum: 200
    description:
      The xMII signals need series termination on the driver side to match both
      the output driver impedance and the line characteristic impedance, to
      prevent reflections and EMI problems. Select a resistance value which is
      supported by the builtin resistors of the PHY, otherwise the resistors may
      have to be placed on board. When omitted, the PHYs default will be left as
      is.

  leds:
    type: object

    properties:
      '#address-cells':
        const: 1

      '#size-cells':
        const: 0

    patternProperties:
      '^led@[a-f0-9]+$':
        $ref: /schemas/leds/common.yaml#

        properties:
          reg:
            maxItems: 1
            description:
              This defines the LED index in the PHY or the MAC. It's really
              driver dependent and required for ports that define multiple
              LED for the same port.

        required:
          - reg

        unevaluatedProperties: false

    additionalProperties: false

  mdi:
    type: object

    patternProperties:
      '^connector-[0-9]+$':
        $ref: /schemas/net/ethernet-connector.yaml#

        unevaluatedProperties: false

    additionalProperties: false

required:
  - reg

additionalProperties: true

examples:
  - |
    #include <dt-bindings/leds/common.h>

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

            leds {
                #address-cells = <1>;
                #size-cells = <0>;

                led@0 {
                    reg = <0>;
                    color = <LED_COLOR_ID_WHITE>;
                    function = LED_FUNCTION_LAN;
                    default-state = "keep";
                };
            };
            /* Fast Ethernet port, with only 2 pairs wired */
            mdi {
                connector-0 {
                    pairs = <2>;
                    media = "BaseT";
                };
            };
        };
    };