Re: [PATCH net-next 4/4] checkpatch: check for comment explaining rgmii(|-rxid|-txid) PHY modes

[Matthias Schiffer]

On Tue, 2025-04-15 at 13:15 +0200, Maxime Chevallier wrote:
> On Tue, 15 Apr 2025 12:18:04 +0200
> Matthias Schiffer <matthias.schiffer@xxxxxxxxxxxxxxx> wrote:
> 
> > Historially, the RGMII PHY modes specified in Device Trees have been
>   ^^^^^^^^^^^
>   Historically
> > used inconsistently, often referring to the usage of delays on the PHY
> > side rather than describing the board; many drivers still implement this
> > incorrectly.
> > 
> > Require a comment in Devices Trees using these modes (usually mentioning
> > that the delay is relalized on the PCB), so we can avoid adding more
> > incorrect uses (or will at least notice which drivers still need to be
> > fixed).
> > 
> > Suggested-by: Andrew Lunn <andrew@xxxxxxx>
> > Signed-off-by: Matthias Schiffer <matthias.schiffer@xxxxxxxxxxxxxxx>
> > ---
> >  Documentation/dev-tools/checkpatch.rst |  9 +++++++++
> >  scripts/checkpatch.pl                  | 11 +++++++++++
> >  2 files changed, 20 insertions(+)
> > 
> > diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> > index abb3ff6820766..8692d3bc155f1 100644
> > --- a/Documentation/dev-tools/checkpatch.rst
> > +++ b/Documentation/dev-tools/checkpatch.rst
> > @@ -513,6 +513,15 @@ Comments
> >  
> >      See: https://lore.kernel.org/lkml/20131006222342.GT19510@leaf/
> >  
> > +  **UNCOMMENTED_RGMII_MODE**
> > +    Historially, the RGMII PHY modes specified in Device Trees have been
>        ^^^^^^^^^^^
>       	 Historically
> > +    used inconsistently, often referring to the usage of delays on the PHY
> > +    side rather than describing the board.
> > +
> > +    PHY modes "rgmii", "rgmii-rxid" and "rgmii-txid" modes require the clock
> > +    signal to be delayed on the PCB; this unusual configuration should be
> > +    described in a comment. If they are not (meaning that the delay is realized
> > +    internally in the MAC or PHY), "rgmii-id" is the correct PHY mode.
> >  
> >  Commit message
> >  --------------
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> > index 784912f570e9d..57fcbd4b63ede 100755
> > --- a/scripts/checkpatch.pl
> > +++ b/scripts/checkpatch.pl
> > @@ -3735,6 +3735,17 @@ sub process {
> >  			}
> >  		}
> >  
> > +# Check for RGMII phy-mode with delay on PCB
> > +		if ($realfile =~ /\.dtsi?$/ && $line =~ /^\+\s*(phy-mode|phy-connection-type)\s*=\s*"/ &&
> > +		    !ctx_has_comment($first_line, $linenr)) {
> > +			my $prop = $1;
> > +			my $mode = get_quoted_string($line, $rawline);
> > +			if ($mode =~ /^"rgmii(?:|-rxid|-txid)"$/) {
> > +				CHK("UNCOMMENTED_RGMII_MODE",
> > +				    "$prop $mode without comment -- delays on the PCB should be described, otherwise use \"rgmii-id\"\n" . $herecurr);
> > +			}
> > +		}
> > +
> 
> My Perl-fu isn't good enough for me to review this properly... I think
> though that Andrew mentioned something along the lines of 'Comment
> should include PCB somewhere', but I don't know if this is easily
> doable with checkpatch though.
> 
> Maxime

I think it can be done using ctx_locate_comment instead of ctx_has_comment, but
I decided against it - requiring to have a comment at all should be sufficient
to make people think about the used mode, and a comment with a bad explanation
would hopefully be caught during review.

Thanks,
Matthias



-- 
TQ-Systems GmbH | Mühlstraße 2, Gut Delling | 82229 Seefeld, Germany
Amtsgericht München, HRB 105018
Geschäftsführer: Detlef Schneider, Rüdiger Stahl, Stefan Schneider
https://www.tq-group.com/