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

[Oleksij Rempel]

On Thu, Dec 05, 2024 at 12:09:55PM +0000, Russell King (Oracle) wrote:
> 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@xxxxxxxxxxxxxx>
> > > ---
> > >   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.

Ok, i'll send a preparation patch to make it consequently for all
callbacks in this struct.

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |