linux-kernel - [PATCH] dmaengine: shdma: correct most kernel-doc issues in shdma-base.h

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>] [day] [month] [year] [list]

Message-ID: <20251104002001.445297-1-rdunlap@infradead.org>
Date: Mon,  3 Nov 2025 16:20:01 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: linux-kernel@...r.kernel.org
Cc: Randy Dunlap <rdunlap@...radead.org>,
	Guennadi Liakhovetski <g.liakhovetski@....de>,
	Paul Mundt <lethal@...ux-sh.org>,
	Vinod Koul <vkoul@...nel.org>,
	dmaengine@...r.kernel.org,
	linux-sh@...r.kernel.org
Subject: [PATCH] dmaengine: shdma: correct most kernel-doc issues in shdma-base.h

Fix kernel-doc comments in include/linux/shdma-base.h to avoid
most warnings:

- prefix an enum name with "enum"
- prefix enum values with '@'
- prefix struct member names with '@'

shdma-base.h:28: warning: cannot understand function prototype:
 'enum shdma_pm_state '
Warning: shdma-base.h:103 struct member 'desc_completed' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'halt_channel' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'channel_busy' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'slave_addr' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'desc_setup' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'set_slave' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'setup_xfer' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'start_xfer' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'embedded_desc' not described
 in 'shdma_ops'
Warning: shdma-base.h:103 struct member 'chan_irq' not described
 in 'shdma_ops'

This one is not fixed: from 4f46f8ac80416:
Warning: shdma-base.h:103 struct member 'get_partial' not described
 in 'shdma_ops'

Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
---
Cc: Guennadi Liakhovetski <g.liakhovetski@....de>
Cc: Paul Mundt <lethal@...ux-sh.org>
Cc: Vinod Koul <vkoul@...nel.org>
Cc: dmaengine@...r.kernel.org
Cc: linux-sh@...r.kernel.org
---
 include/linux/shdma-base.h |   28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

--- linux-next-20251103.orig/include/linux/shdma-base.h
+++ linux-next-20251103/include/linux/shdma-base.h
@@ -19,11 +19,11 @@
 #include <linux/types.h>
 
 /**
- * shdma_pm_state - DMA channel PM state
- * SHDMA_PM_ESTABLISHED:	either idle or during data transfer
- * SHDMA_PM_BUSY:		during the transfer preparation, when we have to
+ * enum shdma_pm_state - DMA channel PM state
+ * @SHDMA_PM_ESTABLISHED:	either idle or during data transfer
+ * @SHDMA_PM_BUSY:		during the transfer preparation, when we have to
  *				drop the lock temporarily
- * SHDMA_PM_PENDING:	transfers pending
+ * @SHDMA_PM_PENDING:	transfers pending
  */
 enum shdma_pm_state {
 	SHDMA_PM_ESTABLISHED,
@@ -74,18 +74,18 @@ struct shdma_chan {
 
 /**
  * struct shdma_ops - simple DMA driver operations
- * desc_completed:	return true, if this is the descriptor, that just has
+ * @desc_completed:	return true, if this is the descriptor, that just has
  *			completed (atomic)
- * halt_channel:	stop DMA channel operation (atomic)
- * channel_busy:	return true, if the channel is busy (atomic)
- * slave_addr:		return slave DMA address
- * desc_setup:		set up the hardware specific descriptor portion (atomic)
- * set_slave:		bind channel to a slave
- * setup_xfer:		configure channel hardware for operation (atomic)
- * start_xfer:		start the DMA transfer (atomic)
- * embedded_desc:	return Nth struct shdma_desc pointer from the
+ * @halt_channel:	stop DMA channel operation (atomic)
+ * @channel_busy:	return true, if the channel is busy (atomic)
+ * @slave_addr:		return slave DMA address
+ * @desc_setup:		set up the hardware specific descriptor portion (atomic)
+ * @set_slave:		bind channel to a slave
+ * @setup_xfer:		configure channel hardware for operation (atomic)
+ * @start_xfer:		start the DMA transfer (atomic)
+ * @embedded_desc:	return Nth struct shdma_desc pointer from the
  *			descriptor array
- * chan_irq:		process channel IRQ, return true if a transfer has
+ * @chan_irq:		process channel IRQ, return true if a transfer has
  *			completed (atomic)
  */
 struct shdma_ops {