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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250220113858.m3c4ign7v5dn2kde@skbuf>
Date: Thu, 20 Feb 2025 13:38:58 +0200
From: Vladimir Oltean <vladimir.oltean@....com>
To: Faizal Rahim <faizal.abdul.rahim@...ux.intel.com>
Cc: Tony Nguyen <anthony.l.nguyen@...el.com>,
	Przemek Kitszel <przemyslaw.kitszel@...el.com>,
	Andrew Lunn <andrew+netdev@...n.ch>,
	"David S . Miller" <davem@...emloft.net>,
	Eric Dumazet <edumazet@...gle.com>,
	Jakub Kicinski <kuba@...nel.org>, Paolo Abeni <pabeni@...hat.com>,
	Maxime Coquelin <mcoquelin.stm32@...il.com>,
	Alexandre Torgue <alexandre.torgue@...s.st.com>,
	Simon Horman <horms@...nel.org>,
	Russell King <linux@...linux.org.uk>,
	Alexei Starovoitov <ast@...nel.org>,
	Daniel Borkmann <daniel@...earbox.net>,
	Jesper Dangaard Brouer <hawk@...nel.org>,
	John Fastabend <john.fastabend@...il.com>,
	Furong Xu <0x1207@...il.com>,
	Russell King <rmk+kernel@...linux.org.uk>,
	Serge Semin <fancer.lancer@...il.com>,
	Xiaolei Wang <xiaolei.wang@...driver.com>,
	Suraj Jaiswal <quic_jsuraj@...cinc.com>,
	Kory Maincent <kory.maincent@...tlin.com>,
	Gal Pressman <gal@...dia.com>,
	Jesper Nilsson <jesper.nilsson@...s.com>,
	Choong Yong Liang <yong.liang.choong@...ux.intel.com>,
	Kunihiko Hayashi <hayashi.kunihiko@...ionext.com>,
	Vinicius Costa Gomes <vinicius.gomes@...el.com>,
	intel-wired-lan@...ts.osuosl.org, netdev@...r.kernel.org,
	linux-kernel@...r.kernel.org,
	linux-stm32@...md-mailman.stormreply.com,
	linux-arm-kernel@...ts.infradead.org, bpf@...r.kernel.org
Subject: Re: [PATCH iwl-next v5 1/9] net: ethtool: mm: extract stmmac
 verification logic into common library

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.