@@ -74,19 +74,17 @@ properties:
7474 - rev-rmii
7575 - moca
7676
77- # RX and TX delays are added by the MAC when required
77+ # RX and TX delays are provided by the PCB. See below
7878 - rgmii
7979
80- # RGMII with internal RX and TX delays provided by the PHY,
81- # the MAC should not add the RX or TX delays in this case
80+ # RX and TX delays are not provided by the PCB. This is the most
81+ # frequent case. See below
8282 - rgmii-id
8383
84- # RGMII with internal RX delay provided by the PHY, the MAC
85- # should not add an RX delay in this case
84+ # TX delay is provided by the PCB. See below
8685 - rgmii-rxid
8786
88- # RGMII with internal TX delay provided by the PHY, the MAC
89- # should not add an TX delay in this case
87+ # RX delay is provided by the PCB. See below
9088 - rgmii-txid
9189 - rtbi
9290 - smii
@@ -286,4 +284,89 @@ allOf:
286284
287285additionalProperties : true
288286
287+ # Informative
288+ # ===========
289+ #
290+ # 'phy-modes' & 'phy-connection-type' properties 'rgmii', 'rgmii-id',
291+ # 'rgmii-rxid', and 'rgmii-txid' are frequently used wrongly by
292+ # developers. This informative section clarifies their usage.
293+ #
294+ # The RGMII specification requires a 2ns delay between the data and
295+ # clock signals on the RGMII bus. How this delay is implemented is not
296+ # specified.
297+ #
298+ # One option is to make the clock traces on the PCB longer than the
299+ # data traces. A sufficiently difference in length can provide the 2ns
300+ # delay. If both the RX and TX delays are implemented in this manner,
301+ # 'rgmii' should be used, so indicating the PCB adds the delays.
302+ #
303+ # If the PCB does not add these delays via extra long traces,
304+ # 'rgmii-id' should be used. Here, 'id' refers to 'internal delay',
305+ # where either the MAC or PHY adds the delay.
306+ #
307+ # If only one of the two delays are implemented via extra long clock
308+ # lines, either 'rgmii-rxid' or 'rgmii-txid' should be used,
309+ # indicating the MAC or PHY should implement one of the delays
310+ # internally, while the PCB implements the other delay.
311+ #
312+ # Device Tree describes hardware, and in this case, it describes the
313+ # PCB between the MAC and the PHY, if the PCB implements delays or
314+ # not.
315+ #
316+ # In practice, very few PCBs make use of extra long clock lines. Hence
317+ # any RGMII phy mode other than 'rgmii-id' is probably wrong, and is
318+ # unlikely to be accepted during review without details provided in
319+ # the commit description and comments in the .dts file.
320+ #
321+ # When the PCB does not implement the delays, the MAC or PHY must. As
322+ # such, this is software configuration, and so not described in Device
323+ # Tree.
324+ #
325+ # The following describes how Linux implements the configuration of
326+ # the MAC and PHY to add these delays when the PCB does not. As stated
327+ # above, developers often get this wrong, and the aim of this section
328+ # is reduce the frequency of these errors by Linux developers. Other
329+ # users of the Device Tree may implement it differently, and still be
330+ # consistent with both the normative and informative description
331+ # above.
332+ #
333+ # By default in Linux, when using phylib/phylink, the MAC is expected
334+ # to read the 'phy-mode' from Device Tree, not implement any delays,
335+ # and pass the value to the PHY. The PHY will then implement delays as
336+ # specified by the 'phy-mode'. The PHY should always be reconfigured
337+ # to implement the needed delays, replacing any setting performed by
338+ # strapping or the bootloader, etc.
339+ #
340+ # Experience to date is that all PHYs which implement RGMII also
341+ # implement the ability to add or not add the needed delays. Hence
342+ # this default is expected to work in all cases. Ignoring this default
343+ # is likely to be questioned by Reviews, and require a strong argument
344+ # to be accepted.
345+ #
346+ # There are a small number of cases where the MAC has hard coded
347+ # delays which cannot be disabled. The 'phy-mode' only describes the
348+ # PCB. The inability to disable the delays in the MAC does not change
349+ # the meaning of 'phy-mode'. It does however mean that a 'phy-mode' of
350+ # 'rgmii' is now invalid, it cannot be supported, since both the PCB
351+ # and the MAC and PHY adding delays cannot result in a functional
352+ # link. Thus the MAC should report a fatal error for any modes which
353+ # cannot be supported. When the MAC implements the delay, it must
354+ # ensure that the PHY does not also implement the same delay. So it
355+ # must modify the phy-mode it passes to the PHY, removing the delay it
356+ # has added. Failure to remove the delay will result in a
357+ # non-functioning link.
358+ #
359+ # Sometimes there is a need to fine tune the delays. Often the MAC or
360+ # PHY can perform this fine tuning. In the MAC node, the Device Tree
361+ # properties 'rx-internal-delay-ps' and 'tx-internal-delay-ps' should
362+ # be used to indicate fine tuning performed by the MAC. The values
363+ # expected here are small. A value of 2000ps, i.e 2ns, and a phy-mode
364+ # of 'rgmii' will not be accepted by Reviewers.
365+ #
366+ # If the PHY is to perform fine tuning, the properties
367+ # 'rx-internal-delay-ps' and 'tx-internal-delay-ps' in the PHY node
368+ # should be used. When the PHY is implementing delays, e.g. 'rgmii-id'
369+ # these properties should have a value near to 2000ps. If the PCB is
370+ # implementing delays, e.g. 'rgmii', a small value can be used to fine
371+ # tune the delay added by the PCB.
289372...
0 commit comments