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