linux-kernel - Re: [PATCH net-next v1 4/7] phy: introduce optional polling interface for PHY statistics

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <Z1GYEyQ6vxK67Yh1@shell.armlinux.org.uk>
Date: Thu, 5 Dec 2024 12:09:55 +0000
From: "Russell King (Oracle)" <linux@...linux.org.uk>
To: Mateusz Polchlopek <mateusz.polchlopek@...el.com>
Cc: Oleksij Rempel <o.rempel@...gutronix.de>,
	"David S. Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Andrew Lunn <andrew+netdev@...n.ch>,
	Heiner Kallweit <hkallweit1@...il.com>,
	Jonathan Corbet <corbet@....net>, kernel@...gutronix.de,
	linux-kernel@...r.kernel.org, netdev@...r.kernel.org,
	Simon Horman <horms@...nel.org>,
	Maxime Chevallier <maxime.chevallier@...tlin.com>,
	linux-doc@...r.kernel.org
Subject: Re: [PATCH net-next v1 4/7] phy: introduce optional polling
 interface for PHY statistics

On Thu, Dec 05, 2024 at 09:14:08AM +0100, Mateusz Polchlopek wrote:
> On 12/3/2024 8:56 AM, Oleksij Rempel wrote:
> > Add an optional polling interface for PHY statistics to simplify driver
> > implementation. Drivers can request the PHYlib to handle the polling task by
> > explicitly setting the `PHY_POLL_STATS` flag in their driver configuration.
> > 
> > Signed-off-by: Oleksij Rempel <o.rempel@...gutronix.de>
> > ---
> >   drivers/net/phy/phy.c | 15 +++++++++++++++
> >   include/linux/phy.h   |  6 ++++++
> >   2 files changed, 21 insertions(+)
> > 
> > diff --git a/drivers/net/phy/phy.c b/drivers/net/phy/phy.c
> > index 0d20b534122b..b10ee9223fc9 100644
> > --- a/drivers/net/phy/phy.c
> > +++ b/drivers/net/phy/phy.c
> > @@ -1346,6 +1346,18 @@ static int phy_enable_interrupts(struct phy_device *phydev)
> >   	return phy_config_interrupt(phydev, PHY_INTERRUPT_ENABLED);
> >   }
> > +/**
> > + * phy_update_stats - update the PHY statistics
> > + * @phydev: target phy_device struct
> > + */
> 
> As this is newly intoduced function I would love to see the full
> kdoc header, with information what the function returns, like here:
> 
> https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation

As it's an internal phylib function, I don't think there's any need for
kernel-doc unless it's something more complex. It's obvious what the
function itself is doing.

What would be more helpful is to properly document the "update_stats"
method, since that is what PHY drivers are going to implement. Yes, I
know kernel-doc isn't good at that, but look at phylink.h to see how
to do it.

> > @@ -1591,6 +1594,9 @@ static inline bool phy_polling_mode(struct phy_device *phydev)
> >   		if (phydev->drv->flags & PHY_POLL_CABLE_TEST)
> >   			return true;
> > +	if (phydev->drv->update_stats && phydev->drv->flags & PHY_POLL_STATS)
> > +		return true;

Is there a case where ->update_stats would be implemented but we
wouldn't have PHY_POLL_STATS set?

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTP is here! 80Mbps down 10Mbps up. Decent connectivity at last!