On Mon, Apr 21, 2025 at 08:20:29PM +0100, Russell King (Oracle) wrote: > On Tue, Apr 15, 2025 at 12:18:01PM +0200, Matthias Schiffer wrote: > > diff --git a/Documentation/devicetree/bindings/net/ethernet-controller.yaml b/Documentation/devicetree/bindings/net/ethernet-controller.yaml > > index 45819b2358002..2ddc1ce2439a6 100644 > > --- a/Documentation/devicetree/bindings/net/ethernet-controller.yaml > > +++ b/Documentation/devicetree/bindings/net/ethernet-controller.yaml > > @@ -74,19 +74,21 @@ properties: > > - rev-rmii > > - moca > > > > - # RX and TX delays are added by the MAC when required > > + # RX and TX delays are part of the board design (through PCB traces). MAC > > + # and PHY must not add delays. > > - rgmii > > > > - # RGMII with internal RX and TX delays provided by the PHY, > > - # the MAC should not add the RX or TX delays in this case > > + # RGMII with internal RX and TX delays provided by the MAC or PHY. No > > + # delays are included in the board design; this is the most common case > > + # in modern designs. > > - rgmii-id > > > > - # RGMII with internal RX delay provided by the PHY, the MAC > > - # should not add an RX delay in this case > > + # RGMII with internal RX delay provided by the MAC or PHY. TX delay is > > + # part of the board design. > > - rgmii-rxid > > > > - # RGMII with internal TX delay provided by the PHY, the MAC > > - # should not add an TX delay in this case > > + # RGMII with internal TX delay provided by the MAC or PHY. RX delay is > > + # part of the board design. > > - rgmii-txid > > - rtbi > > - smii > > Sorry, but I don't think this wording improves the situation - in fact, > I think it makes the whole thing way more confusing. > > Scenario 1: I'm a network device driver author. I read the above, Okay, > I have a RGMII interface, but I need delays to be added. I'll detect > when RGMII-ID is used, and cause the MAC driver to add the delays, but > still pass PHY_INTERFACE_MODE_RGMII_ID to phylib. > > Scenario 2: I'm writing a DT file for a board. Hmm, so if I specify > rgmii because the delays are implemented in the traces, but I need to > fine-tune them. However, the documentation says that delays must not > be added by the MAC or the PHY so how do I adjust them. I know, I'll > use rgmii-id because that allows delays! > > I suspect neither of these two are really want you mean, but given > this wording, that's exactly where it leads - which is more > confusion and less proper understanding. These DT documents are supposed to be normative and OS agnostic. I wounder what the DT Maintainers will say if we add an Informative section afterwards giving a detailed description of how Linux actually implements these normative statements? It will need to open with a clear statement that it is describing Linux behaviour, and other OSes can implement the normative part in other ways and still be compliant, but that Linux has seen a lot of broken implementations and so wants to add Informative information to guide Linux developers. Andrew
