[PATCH net-next 1/4] dt-bindings: net: ethernet-controller: update descriptions of RGMII modes

[Andrew Lunn]

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