1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/net/ethernet-phy.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Ethernet PHY Common Properties
8
9maintainers:
10  - Andrew Lunn <andrew@lunn.ch>
11  - Florian Fainelli <f.fainelli@gmail.com>
12  - Heiner Kallweit <hkallweit1@gmail.com>
13
14# The dt-schema tools will generate a select statement first by using
15# the compatible, and second by using the node name if any. In our
16# case, the node name is the one we want to match on, while the
17# compatible is optional.
18select:
19  properties:
20    $nodename:
21      pattern: "^ethernet-phy(@[a-f0-9]+)?$"
22
23  required:
24    - $nodename
25
26properties:
27  $nodename:
28    pattern: "^ethernet-phy(@[a-f0-9]+)?$"
29
30  compatible:
31    oneOf:
32      - const: ethernet-phy-ieee802.3-c22
33        description: PHYs that implement IEEE802.3 clause 22
34      - const: ethernet-phy-ieee802.3-c45
35        description: PHYs that implement IEEE802.3 clause 45
36      - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
37        description:
38          If the PHY reports an incorrect ID (or none at all) then the
39          compatible list may contain an entry with the correct PHY ID
40          in the above form.
41          The first group of digits is the 16 bit Phy Identifier 1
42          register, this is the chip vendor OUI bits 3:18. The
43          second group of digits is the Phy Identifier 2 register,
44          this is the chip vendor OUI bits 19:24, followed by 10
45          bits of a vendor specific ID.
46      - items:
47          - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
48          - const: ethernet-phy-ieee802.3-c22
49      - items:
50          - pattern: "^ethernet-phy-id[a-f0-9]{4}\\.[a-f0-9]{4}$"
51          - const: ethernet-phy-ieee802.3-c45
52
53  reg:
54    minimum: 0
55    maximum: 31
56    description:
57      The ID number for the PHY.
58
59  interrupts:
60    maxItems: 1
61
62  max-speed:
63    enum:
64      - 10
65      - 100
66      - 1000
67      - 2500
68      - 5000
69      - 10000
70      - 20000
71      - 25000
72      - 40000
73      - 50000
74      - 56000
75      - 100000
76      - 200000
77    description:
78      Maximum PHY supported speed in Mbits / seconds.
79
80  phy-10base-t1l-2.4vpp:
81    description: |
82      tristate, request/disable 2.4 Vpp operating mode. The values are:
83      0: Disable 2.4 Vpp operating mode.
84      1: Request 2.4 Vpp operating mode from link partner.
85      Absence of this property will leave configuration to default values.
86    $ref: /schemas/types.yaml#/definitions/uint32
87    enum: [0, 1]
88
89  broken-turn-around:
90    $ref: /schemas/types.yaml#/definitions/flag
91    description:
92      If set, indicates the PHY device does not correctly release
93      the turn around line low at end of the control phase of the
94      MDIO transaction.
95
96  brr-mode:
97    $ref: /schemas/types.yaml#/definitions/flag
98    description:
99      If set, indicates the network cable interface is an alternative one as
100      defined in the BroadR-Reach link mode specification under 1BR-100 and
101      1BR-10 names. The PHY must be configured to operate in BroadR-Reach mode
102      by software.
103
104  clocks:
105    maxItems: 1
106    description:
107      External clock connected to the PHY. If not specified it is assumed
108      that the PHY uses a fixed crystal or an internal oscillator.
109
110  enet-phy-lane-swap:
111    $ref: /schemas/types.yaml#/definitions/flag
112    description:
113      If set, indicates the PHY will swap the TX/RX lanes to
114      compensate for the board being designed with the lanes
115      swapped.
116
117  enet-phy-lane-no-swap:
118    $ref: /schemas/types.yaml#/definitions/flag
119    description:
120      If set, indicates that PHY will disable swap of the
121      TX/RX lanes. This property allows the PHY to work correctly after
122      e.g. wrong bootstrap configuration caused by issues in PCB
123      layout design.
124
125  eee-broken-100tx:
126    $ref: /schemas/types.yaml#/definitions/flag
127    description:
128      Mark the corresponding energy efficient ethernet mode as
129      broken and request the ethernet to stop advertising it.
130
131  eee-broken-1000t:
132    $ref: /schemas/types.yaml#/definitions/flag
133    description:
134      Mark the corresponding energy efficient ethernet mode as
135      broken and request the ethernet to stop advertising it.
136
137  eee-broken-10gt:
138    $ref: /schemas/types.yaml#/definitions/flag
139    description:
140      Mark the corresponding energy efficient ethernet mode as
141      broken and request the ethernet to stop advertising it.
142
143  eee-broken-1000kx:
144    $ref: /schemas/types.yaml#/definitions/flag
145    description:
146      Mark the corresponding energy efficient ethernet mode as
147      broken and request the ethernet to stop advertising it.
148
149  eee-broken-10gkx4:
150    $ref: /schemas/types.yaml#/definitions/flag
151    description:
152      Mark the corresponding energy efficient ethernet mode as
153      broken and request the ethernet to stop advertising it.
154
155  eee-broken-10gkr:
156    $ref: /schemas/types.yaml#/definitions/flag
157    description:
158      Mark the corresponding energy efficient ethernet mode as
159      broken and request the ethernet to stop advertising it.
160
161  timing-role:
162    $ref: /schemas/types.yaml#/definitions/string
163    enum:
164      - forced-master
165      - forced-slave
166      - preferred-master
167      - preferred-slave
168    description: |
169      Specifies the timing role of the PHY in the network link. This property is
170      required for setups where the role must be explicitly assigned via the
171      device tree due to limitations in hardware strapping or incorrect strap
172      configurations.
173      It is applicable to Single Pair Ethernet (1000/100/10Base-T1) and other
174      PHY types, including 1000Base-T, where it controls whether the PHY should
175      be a master (clock source) or a slave (clock receiver).
176
177      - 'forced-master': The PHY is forced to operate as a master.
178      - 'forced-slave': The PHY is forced to operate as a slave.
179      - 'preferred-master': Prefer the PHY to be master but allow negotiation.
180      - 'preferred-slave': Prefer the PHY to be slave but allow negotiation.
181
182  pses:
183    $ref: /schemas/types.yaml#/definitions/phandle-array
184    maxItems: 1
185    description:
186      Specifies a reference to a node representing a Power Sourcing Equipment.
187
188  phy-is-integrated:
189    $ref: /schemas/types.yaml#/definitions/flag
190    description:
191      If set, indicates that the PHY is integrated into the same
192      physical package as the Ethernet MAC. If needed, muxers
193      should be configured to ensure the integrated PHY is
194      used. The absence of this property indicates the muxers
195      should be configured so that the external PHY is used.
196
197  resets:
198    maxItems: 1
199
200  reset-names:
201    const: phy
202
203  reset-gpios:
204    maxItems: 1
205    description:
206      The GPIO phandle and specifier for the PHY reset signal.
207
208  reset-assert-us:
209    description:
210      Delay after the reset was asserted in microseconds. If this
211      property is missing the delay will be skipped.
212
213  reset-deassert-us:
214    description:
215      Delay after the reset was deasserted in microseconds. If
216      this property is missing the delay will be skipped.
217
218  sfp:
219    $ref: /schemas/types.yaml#/definitions/phandle
220    description:
221      Specifies a reference to a node representing a SFP cage.
222
223  rx-internal-delay-ps:
224    description: |
225      RGMII Receive PHY Clock Delay defined in pico seconds.  This is used for
226      PHY's that have configurable RX internal delays.  If this property is
227      present then the PHY applies the RX delay.
228
229  tx-internal-delay-ps:
230    description: |
231      RGMII Transmit PHY Clock Delay defined in pico seconds.  This is used for
232      PHY's that have configurable TX internal delays. If this property is
233      present then the PHY applies the TX delay.
234
235  tx-amplitude-100base-tx-percent:
236    description:
237      Transmit amplitude gain applied for 100BASE-TX. 100% matches 2V
238      peak-to-peak specified in ANSI X3.263. When omitted, the PHYs default
239      will be left as is.
240
241  mac-termination-ohms:
242    maximum: 200
243    description:
244      The xMII signals need series termination on the driver side to match both
245      the output driver impedance and the line characteristic impedance, to
246      prevent reflections and EMI problems. Select a resistance value which is
247      supported by the builtin resistors of the PHY, otherwise the resistors may
248      have to be placed on board. When omitted, the PHYs default will be left as
249      is.
250
251  leds:
252    type: object
253
254    properties:
255      '#address-cells':
256        const: 1
257
258      '#size-cells':
259        const: 0
260
261    patternProperties:
262      '^led@[a-f0-9]+$':
263        $ref: /schemas/leds/common.yaml#
264
265        properties:
266          reg:
267            maxItems: 1
268            description:
269              This define the LED index in the PHY or the MAC. It's really
270              driver dependent and required for ports that define multiple
271              LED for the same port.
272
273        required:
274          - reg
275
276        unevaluatedProperties: false
277
278    additionalProperties: false
279
280required:
281  - reg
282
283additionalProperties: true
284
285examples:
286  - |
287    #include <dt-bindings/leds/common.h>
288
289    ethernet {
290        #address-cells = <1>;
291        #size-cells = <0>;
292
293        ethernet-phy@0 {
294            compatible = "ethernet-phy-id0141.0e90", "ethernet-phy-ieee802.3-c45";
295            interrupt-parent = <&PIC>;
296            interrupts = <35 1>;
297            reg = <0>;
298
299            resets = <&rst 8>;
300            reset-names = "phy";
301            reset-gpios = <&gpio1 4 1>;
302            reset-assert-us = <1000>;
303            reset-deassert-us = <2000>;
304
305            leds {
306                #address-cells = <1>;
307                #size-cells = <0>;
308
309                led@0 {
310                    reg = <0>;
311                    color = <LED_COLOR_ID_WHITE>;
312                    function = LED_FUNCTION_LAN;
313                    default-state = "keep";
314                };
315            };
316        };
317    };
318