[PATCH net-next v2] sfc: fix stale kernel-doc member names in net_driver.h

[PATCH net-next v2] sfc: fix stale kernel-doc member names in net_driver.h

[Arnav Kapoor]

Several kernel-doc comments in net_driver.h describe struct members that
have since been renamed or removed, and the EFX_MAX_FRAME_LEN() comment
is separated from the macro by the EFX_FRAME_PAD define. kernel-doc
reports:

  Excess struct member 'state' description in 'efx_channel'
  Excess struct member 'state_lock' description in 'efx_channel'
  Excess struct member 'indir_table' description in 'efx_rss_context'
  Excess struct member 'irq_rx_mod_step_us' description in 'efx_nic'
  Excess struct member 'tx_queue' description in 'efx_nic'
  Excess struct member 'rx_queue' description in 'efx_nic'
  Excess struct member 'extra_channel_types' description in 'efx_nic'
  expecting prototype for EFX_MAX_FRAME_LEN(). Prototype was for
  EFX_FRAME_PAD() instead

along with "not described" warnings for the renamed members.

Fix the member names to match the structs, drop the entries for members
that no longer exist, and move the EFX_FRAME_PAD define above the
EFX_MAX_FRAME_LEN() comment, documenting its @mtu parameter.

kernel-doc -Wall also reports three members that are not described
because nothing in the driver uses them any more, so remove them rather
than document them:

  - efx_channel::busy_poll_state, left behind when commit e7fe9491261e
    ("sfc: get rid of custom busy polling code") removed its users.
    @state and @state_lock above were its old kernel-doc entries.
  - efx_tx_queue::flush_outstanding, only used by the Falcon/Siena
    flush code, which commit 36ff6393292d ("sfc: Move Siena specific
    files") moved into siena/ with its own copy of the struct.
  - efx_rx_queue::min_overfill, whose kernel-doc entry and only
    assignment were removed by commit ecc910f520ba ("sfc: Make the dmaq
    size a run-time setting (rather than compile-time)").

The warnings were found with scripts/kernel-doc -Wall. I don't have sfc
hardware; this is compile-tested only.

No functional change.

Assisted-by: LLM
Signed-off-by: Arnav Kapoor <kapoorarnav43@gmail.com>
---
Changes in v2:
- Remove busy_poll_state, flush_outstanding and min_overfill, which are
  unused, instead of leaving them undocumented (Simon)
- Use the Assisted-by format from coding-assistants.rst

net_driver.h has further members with no kernel-doc description,
mostly in struct efx_nic and struct efx_nic_type. Those are in use, so
I'll document them in a separate patch.

W=1 build of drivers/net/ethernet/sfc/ shows no new warnings.

v1: https://lore.kernel.org/all/20261003055443.144554-1-kapoorarnav43@gmail.com/

 drivers/net/ethernet/sfc/net_driver.h | 21 +++++++--------------
 1 file changed, 7 insertions(+), 14 deletions(-)

diff --git a/drivers/net/ethernet/sfc/net_driver.h b/drivers/net/ethernet/sfc/net_driver.h
index 3964b2c56609..71144bb4c6c8 100644
--- a/drivers/net/ethernet/sfc/net_driver.h
+++ b/drivers/net/ethernet/sfc/net_driver.h
@@ -314,7 +314,6 @@ struct efx_tx_queue {
 	/* Members shared between paths and sometimes updated */
 	unsigned int empty_read_count ____cacheline_aligned_in_smp;
 #define EFX_EMPTY_COUNT_VALID 0x80000000
-	atomic_t flush_outstanding;
 };
 
 #define EFX_TX_CB_ORDER	7
@@ -431,7 +430,6 @@ struct efx_rx_queue {
 	unsigned int max_fill;
 	unsigned int fast_fill_trigger;
 	unsigned int min_fill;
-	unsigned int min_overfill;
 	unsigned int recycle_count;
 	struct timer_list slow_fill;
 	unsigned int slow_fill_count;
@@ -467,8 +465,6 @@ enum efx_sync_events_state {
  * @irq_moderation_us: IRQ moderation value (in microseconds)
  * @napi_dev: Net device used with NAPI
  * @napi_str: NAPI control structure
- * @state: state for NAPI vs busy polling
- * @state_lock: lock protecting @state
  * @eventq: Event queue buffer
  * @eventq_mask: Event queue pointer mask
  * @eventq_read_ptr: Event queue read pointer
@@ -526,9 +522,6 @@ struct efx_channel {
 	unsigned int irq_moderation_us;
 	struct net_device *napi_dev;
 	struct napi_struct napi_str;
-#ifdef CONFIG_NET_RX_BUSY_POLL
-	unsigned long busy_poll_state;
-#endif
 	struct efx_buffer eventq;
 	unsigned int eventq_mask;
 	unsigned int eventq_read_ptr;
@@ -788,7 +781,7 @@ struct efx_rss_context_priv {
  * struct efx_rss_context - an RSS context
  * @priv: hardware-specific state
  * @rx_hash_key: Toeplitz hash key for this RSS context
- * @indir_table: Indirection table for this RSS context
+ * @rx_indir_table: Indirection table for this RSS context
  */
 struct efx_rss_context {
 	struct efx_rss_context_priv priv;
@@ -881,16 +874,14 @@ struct efx_mae;
  * @timer_max_ns: Interrupt timer maximum value, in nanoseconds
  * @irq_rx_adaptive: Adaptive IRQ moderation enabled for RX event queues
  * @irqs_hooked: Channel interrupts are hooked
- * @irq_rx_mod_step_us: Step size for IRQ moderation for RX event queues
+ * @irq_mod_step_us: Step size for IRQ moderation for RX event queues
  * @irq_rx_moderation_us: IRQ moderation time for RX event queues
  * @msg_enable: Log message enable flags
  * @state: Device state number (%STATE_*). Serialised by the rtnl_lock.
  * @reset_pending: Bitmask for pending resets
- * @tx_queue: TX DMA queues
- * @rx_queue: RX DMA queues
  * @channel: Channels
  * @msi_context: Context for each MSI
- * @extra_channel_types: Types of extra (non-traffic) channels that
+ * @extra_channel_type: Types of extra (non-traffic) channels that
  *	should be allocated for this NIC
  * @mae: Details of the Match Action Engine
  * @xdp_tx_queue_count: Number of entries in %xdp_tx_queues.
@@ -1711,8 +1702,11 @@ efx_rx_buf_next(struct efx_rx_queue *rx_queue, struct efx_rx_buffer *rx_buf)
 		return rx_buf + 1;
 }
 
+#define EFX_FRAME_PAD	16
+
 /**
  * EFX_MAX_FRAME_LEN - calculate maximum frame length
+ * @mtu: MTU to calculate the maximum frame length for
  *
  * This calculates the maximum frame length that will be used for a
  * given MTU.  The frame length will be equal to the MTU plus a
@@ -1726,9 +1720,8 @@ efx_rx_buf_next(struct efx_rx_queue *rx_queue, struct efx_rx_buffer *rx_buf)
  * Re-clocking by the XGXS on RX can reduce an IPG to 32 bits (half an
  * XGMII cycle).  If the frame length reaches the maximum value in the
  * same cycle, the XMAC can miss the IPG altogether.  We work around
- * this by adding a further 16 bytes.
+ * this by adding a further 16 bytes (EFX_FRAME_PAD).
  */
-#define EFX_FRAME_PAD	16
 #define EFX_MAX_FRAME_LEN(mtu) \
 	(ALIGN(((mtu) + ETH_HLEN + VLAN_HLEN + ETH_FCS_LEN + EFX_FRAME_PAD), 8))
 
-- 
2.53.0