1# SPDX-License-Identifier: GPL-2.0
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/net/ethernet-controller.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: Ethernet Controller Common Properties
8
9maintainers:
10  - David S. Miller <davem@davemloft.net>
11
12properties:
13  $nodename:
14    pattern: "^ethernet(@.*)?$"
15
16  label:
17    description: Human readable label on a port of a box.
18
19  local-mac-address:
20    description:
21      Specifies the MAC address that was assigned to the network device.
22    $ref: /schemas/types.yaml#/definitions/uint8-array
23    minItems: 6
24    maxItems: 6
25
26  mac-address:
27    description:
28      Specifies the MAC address that was last used by the boot
29      program; should be used in cases where the MAC address assigned
30      to the device by the boot program is different from the
31      local-mac-address property.
32    $ref: /schemas/types.yaml#/definitions/uint8-array
33    minItems: 6
34    maxItems: 6
35
36  max-frame-size:
37    $ref: /schemas/types.yaml#/definitions/uint32
38    description:
39      Maximum transfer unit (IEEE defined MTU), rather than the
40      maximum frame size (there\'s contradiction in the Devicetree
41      Specification).
42
43  max-speed:
44    $ref: /schemas/types.yaml#/definitions/uint32
45    description:
46      Specifies maximum speed in Mbit/s supported by the device.
47
48  nvmem-cells:
49    maxItems: 1
50    description:
51      Reference to an nvmem node for the MAC address
52
53  nvmem-cell-names:
54    const: mac-address
55
56  phy-connection-type:
57    description:
58      Specifies interface type between the Ethernet device and a physical
59      layer (PHY) device.
60    enum:
61      # There is not a standard bus between the MAC and the PHY,
62      # something proprietary is being used to embed the PHY in the
63      # MAC.
64      - internal
65      - mii
66      - gmii
67      - sgmii
68      - psgmii
69      - qsgmii
70      - qusgmii
71      - tbi
72      - rev-mii
73      - rmii
74      - rev-rmii
75      - moca
76
77      # RX and TX delays are provided by the PCB. See below
78      - rgmii
79
80      # RX and TX delays are not provided by the PCB. This is the most
81      # frequent case. See below
82      - rgmii-id
83
84      # TX delay is provided by the PCB. See below
85      - rgmii-rxid
86
87      # RX delay is provided by the PCB. See below
88      - rgmii-txid
89      - rtbi
90      - smii
91      - xgmii
92      - trgmii
93      - 1000base-x
94      - 2500base-x
95      - 5gbase-r
96      - rxaui
97      - xaui
98
99      # 10GBASE-KR, XFI, SFI
100      - 10gbase-kr
101      - usxgmii
102      - 10gbase-r
103      - 25gbase-r
104      - 10g-qxgmii
105
106  phy-mode:
107    $ref: "#/properties/phy-connection-type"
108
109  pcs-handle:
110    $ref: /schemas/types.yaml#/definitions/phandle-array
111    items:
112      maxItems: 1
113    description:
114      Specifies a reference to a node representing a PCS PHY device on a MDIO
115      bus to link with an external PHY (phy-handle) if exists.
116
117  pcs-handle-names:
118    description:
119      The name of each PCS in pcs-handle.
120
121  phy-handle:
122    $ref: /schemas/types.yaml#/definitions/phandle
123    description:
124      Specifies a reference to a node representing a PHY device.
125
126  phy:
127    $ref: "#/properties/phy-handle"
128    deprecated: true
129
130  phy-device:
131    $ref: "#/properties/phy-handle"
132    deprecated: true
133
134  rx-fifo-depth:
135    $ref: /schemas/types.yaml#/definitions/uint32
136    description:
137      The size of the controller\'s receive fifo in bytes. This is used
138      for components that can have configurable receive fifo sizes,
139      and is useful for determining certain configuration settings
140      such as flow control thresholds.
141
142  sfp:
143    $ref: /schemas/types.yaml#/definitions/phandle
144    description:
145      Specifies a reference to a node representing a SFP cage.
146
147  tx-fifo-depth:
148    $ref: /schemas/types.yaml#/definitions/uint32
149    description:
150      The size of the controller\'s transmit fifo in bytes. This
151      is used for components that can have configurable fifo sizes.
152
153  managed:
154    description:
155      Specifies the PHY management type. If auto is set and fixed-link
156      is not specified, it uses MDIO for management.
157    $ref: /schemas/types.yaml#/definitions/string
158    default: auto
159    enum:
160      - auto
161      - in-band-status
162
163  fixed-link:
164    oneOf:
165      - $ref: /schemas/types.yaml#/definitions/uint32-array
166        deprecated: true
167        items:
168          - minimum: 0
169            maximum: 31
170            description:
171              Emulated PHY ID, choose any but unique to the all
172              specified fixed-links
173
174          - enum: [0, 1]
175            description:
176              Duplex configuration. 0 for half duplex or 1 for
177              full duplex
178
179          - enum: [10, 100, 1000, 2500, 10000]
180            description:
181              Link speed in Mbits/sec.
182
183          - enum: [0, 1]
184            description:
185              Pause configuration. 0 for no pause, 1 for pause
186
187          - enum: [0, 1]
188            description:
189              Asymmetric pause configuration. 0 for no asymmetric
190              pause, 1 for asymmetric pause
191      - type: object
192        additionalProperties: false
193        properties:
194          speed:
195            description:
196              Link speed.
197            $ref: /schemas/types.yaml#/definitions/uint32
198            enum: [10, 100, 1000, 2500, 10000]
199
200          full-duplex:
201            $ref: /schemas/types.yaml#/definitions/flag
202            description:
203              Indicates that full-duplex is used. When absent, half
204              duplex is assumed.
205
206          pause:
207            $ref: /schemas/types.yaml#/definitions/flag
208            description:
209              Indicates that pause should be enabled.
210
211          asym-pause:
212            $ref: /schemas/types.yaml#/definitions/flag
213            description:
214              Indicates that asym_pause should be enabled.
215
216          link-gpios:
217            maxItems: 1
218            description:
219              GPIO to determine if the link is up
220
221        required:
222          - speed
223
224  leds:
225    description:
226      Describes the LEDs associated by Ethernet Controller.
227      These LEDs are not integrated in the PHY and PHY doesn't have any
228      control on them. Ethernet Controller regs are used to control
229      these defined LEDs.
230
231    type: object
232
233    properties:
234      '#address-cells':
235        const: 1
236
237      '#size-cells':
238        const: 0
239
240    patternProperties:
241      '^led@[a-f0-9]+$':
242        $ref: /schemas/leds/common.yaml#
243
244        properties:
245          reg:
246            maxItems: 1
247            description:
248              This define the LED index in the PHY or the MAC. It's really
249              driver dependent and required for ports that define multiple
250              LED for the same port.
251
252        required:
253          - reg
254
255        unevaluatedProperties: false
256
257    additionalProperties: false
258
259dependencies:
260  pcs-handle-names: [pcs-handle]
261
262allOf:
263  - if:
264      properties:
265        phy-mode:
266          contains:
267            enum:
268              - rgmii
269              - rgmii-rxid
270              - rgmii-txid
271              - rgmii-id
272    then:
273      properties:
274        rx-internal-delay-ps:
275          description:
276            RGMII Receive Clock Delay defined in pico seconds. This is used for
277            controllers that have configurable RX internal delays. If this
278            property is present then the MAC applies the RX delay.
279        tx-internal-delay-ps:
280          description:
281            RGMII Transmit Clock Delay defined in pico seconds. This is used for
282            controllers that have configurable TX internal delays. If this
283            property is present then the MAC applies the TX delay.
284
285additionalProperties: true
286
287# Informative
288# ===========
289#
290# 'phy-modes' & 'phy-connection-type' properties 'rgmii', 'rgmii-id',
291# 'rgmii-rxid', and 'rgmii-txid' are frequently used wrongly by
292# developers. This informative section clarifies their usage.
293#
294# The RGMII specification requires a 2ns delay between the data and
295# clock signals on the RGMII bus. How this delay is implemented is not
296# specified.
297#
298# One option is to make the clock traces on the PCB longer than the
299# data traces. A sufficiently difference in length can provide the 2ns
300# delay. If both the RX and TX delays are implemented in this manner,
301# 'rgmii' should be used, so indicating the PCB adds the delays.
302#
303# If the PCB does not add these delays via extra long traces,
304# 'rgmii-id' should be used. Here, 'id' refers to 'internal delay',
305# where either the MAC or PHY adds the delay.
306#
307# If only one of the two delays are implemented via extra long clock
308# lines, either 'rgmii-rxid' or 'rgmii-txid' should be used,
309# indicating the MAC or PHY should implement one of the delays
310# internally, while the PCB implements the other delay.
311#
312# Device Tree describes hardware, and in this case, it describes the
313# PCB between the MAC and the PHY, if the PCB implements delays or
314# not.
315#
316# In practice, very few PCBs make use of extra long clock lines. Hence
317# any RGMII phy mode other than 'rgmii-id' is probably wrong, and is
318# unlikely to be accepted during review without details provided in
319# the commit description and comments in the .dts file.
320#
321# When the PCB does not implement the delays, the MAC or PHY must.  As
322# such, this is software configuration, and so not described in Device
323# Tree.
324#
325# The following describes how Linux implements the configuration of
326# the MAC and PHY to add these delays when the PCB does not. As stated
327# above, developers often get this wrong, and the aim of this section
328# is reduce the frequency of these errors by Linux developers. Other
329# users of the Device Tree may implement it differently, and still be
330# consistent with both the normative and informative description
331# above.
332#
333# By default in Linux, when using phylib/phylink, the MAC is expected
334# to read the 'phy-mode' from Device Tree, not implement any delays,
335# and pass the value to the PHY. The PHY will then implement delays as
336# specified by the 'phy-mode'. The PHY should always be reconfigured
337# to implement the needed delays, replacing any setting performed by
338# strapping or the bootloader, etc.
339#
340# Experience to date is that all PHYs which implement RGMII also
341# implement the ability to add or not add the needed delays. Hence
342# this default is expected to work in all cases. Ignoring this default
343# is likely to be questioned by Reviews, and require a strong argument
344# to be accepted.
345#
346# There are a small number of cases where the MAC has hard coded
347# delays which cannot be disabled. The 'phy-mode' only describes the
348# PCB.  The inability to disable the delays in the MAC does not change
349# the meaning of 'phy-mode'. It does however mean that a 'phy-mode' of
350# 'rgmii' is now invalid, it cannot be supported, since both the PCB
351# and the MAC and PHY adding delays cannot result in a functional
352# link. Thus the MAC should report a fatal error for any modes which
353# cannot be supported. When the MAC implements the delay, it must
354# ensure that the PHY does not also implement the same delay. So it
355# must modify the phy-mode it passes to the PHY, removing the delay it
356# has added. Failure to remove the delay will result in a
357# non-functioning link.
358#
359# Sometimes there is a need to fine tune the delays. Often the MAC or
360# PHY can perform this fine tuning. In the MAC node, the Device Tree
361# properties 'rx-internal-delay-ps' and 'tx-internal-delay-ps' should
362# be used to indicate fine tuning performed by the MAC. The values
363# expected here are small. A value of 2000ps, i.e 2ns, and a phy-mode
364# of 'rgmii' will not be accepted by Reviewers.
365#
366# If the PHY is to perform fine tuning, the properties
367# 'rx-internal-delay-ps' and 'tx-internal-delay-ps' in the PHY node
368# should be used. When the PHY is implementing delays, e.g. 'rgmii-id'
369# these properties should have a value near to 2000ps. If the PCB is
370# implementing delays, e.g. 'rgmii', a small value can be used to fine
371# tune the delay added by the PCB.
372...
373