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