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