Re: [PATCH net-next v0 2/3] net: phy: phy_device: Call into the PHY driver to set LED offload

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

On Mon, Jun 19, 2023 at 04:18:29PM +0200, Simon Horman wrote:
> On Sun, Jun 18, 2023 at 07:39:36PM +0200, Andrew Lunn wrote:
> > Linux LEDs can be requested to perform hardware accelerated blinking
> > to indicate link, RX, TX etc. Pass the rules for blinking to the PHY
> > driver, if it implements the ops needed to determine if a given
> > pattern can be offloaded, to offload it, and what the current offload
> > is. Additionally implement the op needed to get what device the LED is
> > for.
> > 
> > Signed-off-by: Andrew Lunn <andrew@lunn.ch>
> 
> ...
> 
> > diff --git a/include/linux/phy.h b/include/linux/phy.h
> > index 11c1e91563d4..1db63fb905c5 100644
> > --- a/include/linux/phy.h
> > +++ b/include/linux/phy.h
> > @@ -1104,6 +1104,20 @@ struct phy_driver {
> >  	int (*led_blink_set)(struct phy_device *dev, u8 index,
> >  			     unsigned long *delay_on,
> >  			     unsigned long *delay_off);
> > +	/* Can the HW support the given rules. Return 0 if yes,
> > +	 * -EOPNOTSUPP if not, or an error code.
> > +	 */
> > +	int (*led_hw_is_supported)(struct phy_device *dev, u8 index,
> > +				   unsigned long rules);
> > +	/* Set the HW to control the LED as described by rules. */
> > +	int (*led_hw_control_set)(struct phy_device *dev, u8 index,
> > +				  unsigned long rules);
> > +	/* Get the rules used to describe how the HW is currently
> > +	 * configure.
> > +	 */
> > +	int (*led_hw_control_get)(struct phy_device *dev, u8 index,
> > +				  unsigned long *rules);
> > +
> 
> Hi Andrew,
> 
> for consistency it would be nice if the comments for
> the new members above was in kernel doc format.

Unfortunately, kerneldoc doesn't understand structures-of-function-
pointers, so one can't document each operation and its parameters
without playing games such as I've done in linux/phylink.h. It involves
listing the prototypes not as function pointers but as normal function
prototypes in a #if 0..#endif section and preceeding each with a
kerneldoc comment describing the function and its parameters in the
normal way.

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