diff mbox series

linux/dmaengine.h: fix a few kernel-doc warnings

Message ID 20241125061508.165099-1-rdunlap@infradead.org (mailing list archive)
State Superseded
Headers show
Series linux/dmaengine.h: fix a few kernel-doc warnings | expand

Commit Message

Randy Dunlap Nov. 25, 2024, 6:15 a.m. UTC 
The comment block for "Interleaved Transfer Request" should not begin
with "/**" since it is not in kernel-doc format.

Fix doc name for enum sum_check_flags.

Fix all (4) missing struct member warnings.

Use "Warning:" for one "Note:" in enum dma_desc_metadata_mode since
scripts/kernel-doc does not allow more than one Note:
per function or identifier description.

This leaves around 49 kernel-doc warnings like:
  include/linux/dmaengine.h:43: warning: Enum value 'DMA_OUT_OF_ORDER' not described in enum 'dma_status'

and another scripts/kernel-doc problem with it not being able to parse
some typedefs.

Fixes: b14dab792dee ("DMAEngine: Define interleaved transfer request api"), Jassi Brar
Fixes: ad283ea4a3ce ("async_tx: add sum check flags")
Fixes: 272420214d26 ("dmaengine: Add DMA_CTRL_REUSE")
Fixes: f067025bc676 ("dmaengine: add support to provide error result from a DMA transation")
Fixes: d38a8c622a1b ("dmaengine: prepare for generic 'unmap' data")
Fixes: 5878853fc938 ("dmaengine: Add API function dmaengine_prep_peripheral_dma_vec()")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jassi Brar <jaswinder.singh@linaro.org>
Cc: Dan Williams <dan.j.williams@intel.com>
Cc: Dave Jiang <dave.jiang@intel.com>
Cc: Paul Cercueil <paul@crapouillou.net>
Cc: Nuno Sa <nuno.sa@analog.com>
Cc: Vinod Koul <vkoul@kernel.org>
Cc: dmaengine@vger.kernel.org
---
 include/linux/dmaengine.h |   13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

Comments

Randy Dunlap Nov. 25, 2024, 6:20 a.m. UTC | #1 
On 11/24/24 10:15 PM, Randy Dunlap wrote:
> The comment block for "Interleaved Transfer Request" should not begin
> with "/**" since it is not in kernel-doc format.
> 
> Fix doc name for enum sum_check_flags.
> 
> Fix all (4) missing struct member warnings.
> 
> Use "Warning:" for one "Note:" in enum dma_desc_metadata_mode since
> scripts/kernel-doc does not allow more than one Note:
> per function or identifier description.
> 
> This leaves around 49 kernel-doc warnings like:
>   include/linux/dmaengine.h:43: warning: Enum value 'DMA_OUT_OF_ORDER' not described in enum 'dma_status'
> 
> and another scripts/kernel-doc problem with it not being able to parse
> some typedefs.
> 
> Fixes: b14dab792dee ("DMAEngine: Define interleaved transfer request api"), Jassi Brar

Oops, I left a note in the line above. I'll fix it for v2 after comments.

> Fixes: ad283ea4a3ce ("async_tx: add sum check flags")
> Fixes: 272420214d26 ("dmaengine: Add DMA_CTRL_REUSE")
> Fixes: f067025bc676 ("dmaengine: add support to provide error result from a DMA transation")
> Fixes: d38a8c622a1b ("dmaengine: prepare for generic 'unmap' data")
> Fixes: 5878853fc938 ("dmaengine: Add API function dmaengine_prep_peripheral_dma_vec()")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jassi Brar <jaswinder.singh@linaro.org>
> Cc: Dan Williams <dan.j.williams@intel.com>
> Cc: Dave Jiang <dave.jiang@intel.com>
> Cc: Paul Cercueil <paul@crapouillou.net>
> Cc: Nuno Sa <nuno.sa@analog.com>
> Cc: Vinod Koul <vkoul@kernel.org>
> Cc: dmaengine@vger.kernel.org
> ---
>  include/linux/dmaengine.h |   13 ++++++++++---
>  1 file changed, 10 insertions(+), 3 deletions(-)
Vinod Koul Dec. 2, 2024, 4:21 p.m. UTC | #2 
On 24-11-24, 22:20, Randy Dunlap wrote:
> 
> 
> On 11/24/24 10:15 PM, Randy Dunlap wrote:
> > The comment block for "Interleaved Transfer Request" should not begin
> > with "/**" since it is not in kernel-doc format.
> > 
> > Fix doc name for enum sum_check_flags.
> > 
> > Fix all (4) missing struct member warnings.
> > 
> > Use "Warning:" for one "Note:" in enum dma_desc_metadata_mode since
> > scripts/kernel-doc does not allow more than one Note:
> > per function or identifier description.
> > 
> > This leaves around 49 kernel-doc warnings like:
> >   include/linux/dmaengine.h:43: warning: Enum value 'DMA_OUT_OF_ORDER' not described in enum 'dma_status'
> > 
> > and another scripts/kernel-doc problem with it not being able to parse
> > some typedefs.
> > 
> > Fixes: b14dab792dee ("DMAEngine: Define interleaved transfer request api"), Jassi Brar
> 
> Oops, I left a note in the line above. I'll fix it for v2 after comments.

lgt,, I guess we can do a v2 now

> 
> > Fixes: ad283ea4a3ce ("async_tx: add sum check flags")
> > Fixes: 272420214d26 ("dmaengine: Add DMA_CTRL_REUSE")
> > Fixes: f067025bc676 ("dmaengine: add support to provide error result from a DMA transation")
> > Fixes: d38a8c622a1b ("dmaengine: prepare for generic 'unmap' data")
> > Fixes: 5878853fc938 ("dmaengine: Add API function dmaengine_prep_peripheral_dma_vec()")
> > Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> > Cc: Jassi Brar <jaswinder.singh@linaro.org>
> > Cc: Dan Williams <dan.j.williams@intel.com>
> > Cc: Dave Jiang <dave.jiang@intel.com>
> > Cc: Paul Cercueil <paul@crapouillou.net>
> > Cc: Nuno Sa <nuno.sa@analog.com>
> > Cc: Vinod Koul <vkoul@kernel.org>
> > Cc: dmaengine@vger.kernel.org
> > ---
> >  include/linux/dmaengine.h |   13 ++++++++++---
> >  1 file changed, 10 insertions(+), 3 deletions(-)
> 
> 
> -- 
> ~Randy
>
diff mbox series

Patch

--- linux-next-20241122.orig/include/linux/dmaengine.h
+++ linux-next-20241122/include/linux/dmaengine.h
@@ -84,7 +84,7 @@  enum dma_transfer_direction {
 	DMA_TRANS_NONE,
 };
 
-/**
+/*
  * Interleaved Transfer Request
  * ----------------------------
  * A chunk is collection of contiguous bytes to be transferred.
@@ -223,7 +223,7 @@  enum sum_check_bits {
 };
 
 /**
- * enum pq_check_flags - result of async_{xor,pq}_zero_sum operations
+ * enum sum_check_flags - result of async_{xor,pq}_zero_sum operations
  * @SUM_CHECK_P_RESULT - 1 if xor zero sum error, 0 otherwise
  * @SUM_CHECK_Q_RESULT - 1 if reed-solomon zero sum error, 0 otherwise
  */
@@ -286,7 +286,7 @@  typedef struct { DECLARE_BITMAP(bits, DM
  *	pointer to the engine's metadata area
  *   4. Read out the metadata from the pointer
  *
- * Note: the two mode is not compatible and clients must use one mode for a
+ * Warning: the two modes are not compatible and clients must use one mode for a
  * descriptor.
  */
 enum dma_desc_metadata_mode {
@@ -594,9 +594,13 @@  struct dma_descriptor_metadata_ops {
  * @phys: physical address of the descriptor
  * @chan: target channel for this operation
  * @tx_submit: accept the descriptor, assign ordered cookie and mark the
+ * @desc_free: driver's callback function to free a resusable descriptor
+ *	after completion
  * descriptor pending. To be pushed on .issue_pending() call
  * @callback: routine to call after this operation is complete
+ * @callback_result: error result from a DMA transaction
  * @callback_param: general parameter to pass to the callback routine
+ * @unmap: hook for generic DMA unmap data
  * @desc_metadata_mode: core managed metadata mode to protect mixed use of
  *	DESC_METADATA_CLIENT or DESC_METADATA_ENGINE. Otherwise
  *	DESC_METADATA_NONE
@@ -827,6 +831,9 @@  struct dma_filter {
  * @device_prep_dma_memset: prepares a memset operation
  * @device_prep_dma_memset_sg: prepares a memset operation over a scatter list
  * @device_prep_dma_interrupt: prepares an end of chain interrupt operation
+ * @device_prep_peripheral_dma_vec: prepares a scatter-gather DMA transfer,
+ *	where the address and size of each segment is located in one entry of
+ *	the dma_vec array.
  * @device_prep_slave_sg: prepares a slave dma operation
  * @device_prep_dma_cyclic: prepare a cyclic dma operation suitable for audio.
  *	The function takes a buffer of size buf_len. The callback function will