On Wed, Feb 19, 2025 at 09:53:41PM -0500, Faizal Rahim wrote: > +/** > + * ethtool_mmsv_stop() - Stop MAC Merge Software Verification > + * @mmsv: MAC Merge Software Verification state > + * > + * Drivers should call this method in a state where the hardware is > + * about to lose state, like ndo_stop() or suspend(), and turning off > + * MAC Merge features would be superfluous. Otherwise, prefer > + * ethtool_mmsv_link_state_handle() with up=false. > + */ > +void ethtool_mmsv_stop(struct ethtool_mmsv *mmsv); > + > +/** > + * ethtool_mmsv_link_state_handle() - Inform MAC Merge Software Verification > + * of link state changes > + * @mmsv: MAC Merge Software Verification state > + * @up: True if device carrier is up and able to pass verification packets > + * > + * Calling context is expected to be from a thread, interrupts enabled. s/thread/task/, I think it's a more conventional way of referring to process context. > + */ > +void ethtool_mmsv_link_state_handle(struct ethtool_mmsv *mmsv, bool up); > + > +/** > + * ethtool_mmsv_event_handle() - Inform MAC Merge Software Verification > + * of interrupt-based events > + * @mmsv: MAC Merge Software Verification state > + * @event: Event which took place (packet transmission or reception) > + * > + * Calling context expects to have interrupts disabled. > + */ > +void ethtool_mmsv_event_handle(struct ethtool_mmsv *mmsv, > + enum ethtool_mmsv_event event); > + > +/** > + * ethtool_mmsv_get_mm() - get_mm() hook for MAC Merge Software Verification > + * @mmsv: MAC Merge Software Verification state > + * @state: see struct ethtool_mm_state > + * > + * Drivers are expected to call this from their ethtool_ops :: get_mm() > + * method. > + */ > +void ethtool_mmsv_get_mm(struct ethtool_mmsv *mmsv, > + struct ethtool_mm_state *state); > + > +/** > + * ethtool_mmsv_set_mm() - set_mm() hook for MAC Merge Software Verification > + * @mmsv: MAC Merge Software Verification state > + * @cfg: see struct ethtool_mm_cfg > + * > + * Drivers are expected to call this from their ethtool_ops :: set_mm() > + * method. > + */ > +void ethtool_mmsv_set_mm(struct ethtool_mmsv *mmsv, struct ethtool_mm_cfg *cfg); > + > +/** > + * ethtool_mmsv_init() - Initialize MAC Merge Software Verification state > + * @mmsv: MAC Merge Software Verification state > + * @dev: Pointer to network interface > + * @ops: Methods for implementing the generic functionality > + * > + * The MAC Merge Software Verification is a timer- and event-based state > + * machine intended for network interfaces which lack a hardware-based > + * TX verification process (as per IEEE 802.3 clause 99.4.3). The timer > + * is managed by the core code, whereas events are supplied by the > + * driver explicitly calling one of the other API functions. > + */ > +void ethtool_mmsv_init(struct ethtool_mmsv *mmsv, struct net_device *dev, > + const struct ethtool_mmsv_ops *ops); The kernel-doc comments are fine, but I think the convention is to put them near the function definitions (in net/ethtool/mm.c) rather than near the function prototypes, for the very simple reason that in the C language, you can have multiple function declarations but a single definition. The kernel-doc for the structures is fine where it is.
