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

["Russell King (Oracle)" <linux@armlinux.org.uk>]

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@pengutronix.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!