diff options
Diffstat (limited to 'Documentation/devicetree/bindings/net/ethernet-controller.yaml')
| -rw-r--r-- | Documentation/devicetree/bindings/net/ethernet-controller.yaml | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml new file mode 100644 index 000000000000..1bafd687dcb1 --- /dev/null +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml @@ -0,0 +1,355 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/net/ethernet-controller.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +title: Ethernet Controller Common Properties + +maintainers: + - David S. Miller <davem@davemloft.net> + +properties: + $nodename: + pattern: "^ethernet(@.*)?$" + + label: + description: Human readable label on a port of a box. + + max-speed: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Specifies maximum speed in Mbit/s supported by the device. + + nvmem-cells: + maxItems: 1 + description: + Reference to an nvmem node for the MAC address + + nvmem-cell-names: + const: mac-address + + phy-connection-type: + description: + Specifies interface type between the Ethernet device and a physical + layer (PHY) device. + enum: + # There is not a standard bus between the MAC and the PHY, + # something proprietary is being used to embed the PHY in the + # MAC. + - internal + - mii + - mii-lite + - gmii + - sgmii + - psgmii + - qsgmii + - qusgmii + - tbi + - rev-mii + - rmii + - rev-rmii + - moca + + # RX and TX delays are provided by the PCB. See below + - rgmii + + # RX and TX delays are not provided by the PCB. This is the most + # frequent case. See below + - rgmii-id + + # TX delay is provided by the PCB. See below + - rgmii-rxid + + # RX delay is provided by the PCB. See below + - rgmii-txid + - rtbi + - smii + - xgmii + - trgmii + - 1000base-x + - 2500base-x + - 5gbase-r + - rxaui + - xaui + + # 10GBASE-KR, XFI, SFI + - 10gbase-kr + - usxgmii + - 10gbase-r + - 25gbase-r + - 10g-qxgmii + + phy-mode: + $ref: "#/properties/phy-connection-type" + + pcs-handle: + $ref: /schemas/types.yaml#/definitions/phandle-array + items: + maxItems: 1 + description: + Specifies a reference to a node representing a PCS PHY device on a MDIO + bus to link with an external PHY (phy-handle) if exists. + + pcs-handle-names: + description: + The name of each PCS in pcs-handle. + + phy-handle: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Specifies a reference to a node representing a PHY device. + + phy: + $ref: "#/properties/phy-handle" + deprecated: true + + phy-device: + $ref: "#/properties/phy-handle" + deprecated: true + + ptp-timer: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Specifies a reference to a node representing an IEEE 1588 PTP device. + + rx-fifo-depth: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The size of the controller\'s receive fifo in bytes. This is used + for components that can have configurable receive fifo sizes, + and is useful for determining certain configuration settings + such as flow control thresholds. + + sfp: + $ref: /schemas/types.yaml#/definitions/phandle + description: + Specifies a reference to a node representing a SFP cage. + + tx-fifo-depth: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + The size of the controller\'s transmit fifo in bytes. This + is used for components that can have configurable fifo sizes. + + managed: + description: + Specifies the PHY management type. If auto is set and fixed-link + is not specified, it uses MDIO for management. + $ref: /schemas/types.yaml#/definitions/string + default: auto + enum: + - auto + - in-band-status + + fixed-link: + oneOf: + - $ref: /schemas/types.yaml#/definitions/uint32-array + deprecated: true + items: + - minimum: 0 + maximum: 31 + description: + Emulated PHY ID, choose any but unique to the all + specified fixed-links + + - enum: [0, 1] + description: + Duplex configuration. 0 for half duplex or 1 for + full duplex + + - enum: [10, 100, 1000, 2500, 10000] + description: + Link speed in Mbits/sec. + + - enum: [0, 1] + description: + Pause configuration. 0 for no pause, 1 for pause + + - enum: [0, 1] + description: + Asymmetric pause configuration. 0 for no asymmetric + pause, 1 for asymmetric pause + - type: object + additionalProperties: false + properties: + speed: + description: + Link speed. + $ref: /schemas/types.yaml#/definitions/uint32 + enum: [10, 100, 1000, 2500, 5000, 10000] + + full-duplex: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that full-duplex is used. When absent, half + duplex is assumed. + + pause: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that pause should be enabled. + + asym-pause: + $ref: /schemas/types.yaml#/definitions/flag + description: + Indicates that asym_pause should be enabled. + + link-gpios: + maxItems: 1 + description: + GPIO to determine if the link is up + + required: + - speed + + leds: + description: + Describes the LEDs associated by Ethernet Controller. + These LEDs are not integrated in the PHY and PHY doesn't have any + control on them. Ethernet Controller regs are used to control + these defined LEDs. + + type: object + + properties: + '#address-cells': + const: 1 + + '#size-cells': + const: 0 + + patternProperties: + '^led@[a-f0-9]+$': + $ref: /schemas/leds/common.yaml# + + properties: + reg: + maxItems: 1 + description: + This defines the LED index in the PHY or the MAC. It's really + driver dependent and required for ports that define multiple + LED for the same port. + + required: + - reg + + unevaluatedProperties: false + + additionalProperties: false + +dependencies: + pcs-handle-names: [pcs-handle] + +allOf: + - $ref: /schemas/net/network-class.yaml# + - if: + properties: + phy-mode: + contains: + enum: + - rgmii + - rgmii-rxid + - rgmii-txid + - rgmii-id + then: + properties: + rx-internal-delay-ps: + description: + RGMII Receive Clock Delay defined in pico seconds. This is used for + controllers that have configurable RX internal delays. If this + property is present then the MAC applies the RX delay. + tx-internal-delay-ps: + description: + RGMII Transmit Clock Delay defined in pico seconds. This is used for + controllers that have configurable TX internal delays. If this + property is present then the MAC applies the TX delay. + +additionalProperties: true + +# Informative +# =========== +# +# 'phy-modes' & 'phy-connection-type' properties 'rgmii', 'rgmii-id', +# 'rgmii-rxid', and 'rgmii-txid' are frequently used wrongly by +# developers. This informative section clarifies their usage. +# +# The RGMII specification requires a 2ns delay between the data and +# clock signals on the RGMII bus. How this delay is implemented is not +# specified. +# +# One option is to make the clock traces on the PCB longer than the +# data traces. A sufficient difference in length can provide the 2ns +# delay. If both the RX and TX delays are implemented in this manner, +# 'rgmii' should be used, so indicating the PCB adds the delays. +# +# If the PCB does not add these delays via extra long traces, +# 'rgmii-id' should be used. Here, 'id' refers to 'internal delay', +# where either the MAC or PHY adds the delay. +# +# If only one of the two delays are implemented via extra long clock +# lines, either 'rgmii-rxid' or 'rgmii-txid' should be used, +# indicating the MAC or PHY should implement one of the delays +# internally, while the PCB implements the other delay. +# +# Device Tree describes hardware, and in this case, it describes the +# PCB between the MAC and the PHY, if the PCB implements delays or +# not. +# +# In practice, very few PCBs make use of extra long clock lines. Hence +# any RGMII phy mode other than 'rgmii-id' is probably wrong, and is +# unlikely to be accepted during review without details provided in +# the commit description and comments in the .dts file. +# +# When the PCB does not implement the delays, the MAC or PHY must. As +# such, this is software configuration, and so not described in Device +# Tree. +# +# The following describes how Linux implements the configuration of +# the MAC and PHY to add these delays when the PCB does not. As stated +# above, developers often get this wrong, and the aim of this section +# is reduce the frequency of these errors by Linux developers. Other +# users of the Device Tree may implement it differently, and still be +# consistent with both the normative and informative description +# above. +# +# By default in Linux, when using phylib/phylink, the MAC is expected +# to read the 'phy-mode' from Device Tree, not implement any delays, +# and pass the value to the PHY. The PHY will then implement delays as +# specified by the 'phy-mode'. The PHY should always be reconfigured +# to implement the needed delays, replacing any setting performed by +# strapping or the bootloader, etc. +# +# Experience to date is that all PHYs which implement RGMII also +# implement the ability to add or not add the needed delays. Hence +# this default is expected to work in all cases. Ignoring this default +# is likely to be questioned by Reviews, and require a strong argument +# to be accepted. +# +# There are a small number of cases where the MAC has hard coded +# delays which cannot be disabled. The 'phy-mode' only describes the +# PCB. The inability to disable the delays in the MAC does not change +# the meaning of 'phy-mode'. It does however mean that a 'phy-mode' of +# 'rgmii' is now invalid, it cannot be supported, since both the PCB +# and the MAC and PHY adding delays cannot result in a functional +# link. Thus the MAC should report a fatal error for any modes which +# cannot be supported. When the MAC implements the delay, it must +# ensure that the PHY does not also implement the same delay. So it +# must modify the phy-mode it passes to the PHY, removing the delay it +# has added. Failure to remove the delay will result in a +# non-functioning link. +# +# Sometimes there is a need to fine tune the delays. Often the MAC or +# PHY can perform this fine tuning. In the MAC node, the Device Tree +# properties 'rx-internal-delay-ps' and 'tx-internal-delay-ps' should +# be used to indicate fine tuning performed by the MAC. The values +# expected here are small. A value of 2000ps, i.e 2ns, and a phy-mode +# of 'rgmii' will not be accepted by Reviewers. +# +# If the PHY is to perform fine tuning, the properties +# 'rx-internal-delay-ps' and 'tx-internal-delay-ps' in the PHY node +# should be used. When the PHY is implementing delays, e.g. 'rgmii-id' +# these properties should have a value near to 2000ps. If the PCB is +# implementing delays, e.g. 'rgmii', a small value can be used to fine +# tune the delay added by the PCB. +... |