| # 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. |
| ... |
