Re: [PATCH iwl-next v5 1/9] net: ethtool: mm: extract stmmac verification logic into common library

[Vladimir Oltean <vladimir.oltean@nxp.com>]

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.