All of lore.kernel.org
 help / color / mirror / Atom feed
* [PATCH] staging: most: dim2: add missing Return: documentation
@ 2026-11-04 20:51 Albu Victor-Marian
  2026-11-05  5:11 ` Dan Carpenter
  2026-11-05 20:21 ` [PATCH v2] " Albu Victor-Marian
  0 siblings, 2 replies; 7+ messages in thread
From: Albu Victor-Marian @ 2026-11-04 20:51 UTC (permalink / raw)
  To: parthiban.veerasooran, christian.gromm
  Cc: gregkh, linux-staging, linux-kernel, Albu Victor-Marian

Add missing Return: descriptions to functions in dim2.c. 

Signed-off-by: Albu Victor-Marian <albu.victor.m@gmail.com>
---
 drivers/staging/most/dim2/dim2.c | 30 ++++++++++++++++++++++++++----
 1 file changed, 26 insertions(+), 4 deletions(-)

diff --git a/drivers/staging/most/dim2/dim2.c b/drivers/staging/most/dim2/dim2.c
index 0e2512d166329..7ed38d5d93f05 100644
--- a/drivers/staging/most/dim2/dim2.c
+++ b/drivers/staging/most/dim2/dim2.c
@@ -156,6 +156,10 @@ void dimcb_on_error(u8 error_id, const char *error_message)
  * @hdm_ch: channel specific data
  *
  * Transfer a buffer from pending_list if the channel is ready
+ *
+ * Return: 0 on success, -EINVAL if hdm_ch is not initialized, -EAGAIN if hdm_ch pending_list is
+ * empty, dim_channel is not ready or there is not enough DBR space, -EFAULT if first MBO bus
+ * address is 0 or dim_channel fails to start
  */
 static int try_start_dim_transfer(struct hdm_channel *hdm_ch)
 {
@@ -211,6 +215,8 @@ static int try_start_dim_transfer(struct hdm_channel *hdm_ch)
  * @data: private data
  *
  * Wait for network status and deliver it to mostcore once it is received
+ *
+ * Return: 0 when the thread stops without error.
  */
 static int deliver_netinfo_thread(void *data)
 {
@@ -392,6 +398,9 @@ static irqreturn_t dim2_task_irq(int irq, void *_dev)
  *
  * Acknowledge the interrupt and service each initialized channel,
  * if needed, in task context.
+ *
+ * Return: IRQ_WAKE_THREAD after acknowledging the interrupt and servicing each
+ * initialized channel.
  */
 static irqreturn_t dim2_ahb_isr(int irq, void *_dev)
 {
@@ -442,7 +451,11 @@ static void complete_all_mbos(struct list_head *head)
  * @ccfg: structure that holds the configuration information
  *
  * Receives configuration information from mostcore and initialize
- * the corresponding channel. Return 0 on success, negative on failure.
+ * the corresponding channel.
+ *
+ * Return: 0 on success, -EINVAL if ch_idx is negative or bigger than or equal to DMA_CHANNELS, the
+ * buffer size of ccfg is too small, sub-buffer size of ccfg is invalid or bad channel type, -EPERM
+ * if hdm_ch is initialized or -ENODEV if init_ctrl_async returns any error value.
  */
 static int configure_channel(struct most_interface *most_iface, int ch_idx,
 			     struct most_channel_config *ccfg)
@@ -561,7 +574,10 @@ static int configure_channel(struct most_interface *most_iface, int ch_idx,
  * @mbo: pointer to the buffer object
  *
  * Push the buffer into pending_list and try to transfer one buffer from
- * pending_list. Return 0 on success, negative on failure.
+ * pending_list.
+ *
+ * Return: 0 on success, -EINVAL if ch_idx is negative or bigger than or equal to DMA_CHANNELS,
+ * -EPERM if hdm_ch is not initialized or -EFAULT if MBO bus address is 0.
  */
 static int enqueue(struct most_interface *most_iface, int ch_idx,
 		   struct mbo *mbo)
@@ -637,7 +653,10 @@ static void request_netinfo(struct most_interface *most_iface, int ch_idx,
  * @ch_idx: corresponding channel ID
  *
  * Destroy a channel and complete all the buffers in both started_list &
- * pending_list. Return 0 on success, negative on failure.
+ * pending_list.
+ *
+ * Return: 0 on success, -EINVAL if ch_idx is negative or bigger than or equal to DMA_CHANNELS,
+ * -EPERM if hdm_ch is not initialized or -EFAULT if HAL failed to close channel.
  */
 static int poison_channel(struct most_interface *most_iface, int ch_idx)
 {
@@ -710,6 +729,8 @@ static struct {
  *
  * By success stores one of the CLK_{NUMBER}FS in the *val and returns 0,
  * otherwise returns -EINVAL.
+ *
+ * Return: 0 on success, -EINVAL if the string in clock_speed does not match any in clk_mt.
  */
 static int get_dim2_clk_speed(const char *clock_speed, u8 *val)
 {
@@ -746,7 +767,8 @@ static void dim2_release(struct device *d)
  * @pdev: platform device structure
  *
  * Register the dim2 interface with mostcore and initialize it.
- * Return 0 on success, negative on failure.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int dim2_probe(struct platform_device *pdev)
 {
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH] staging: most: dim2: add missing Return: documentation
  2026-11-04 20:51 [PATCH] staging: most: dim2: add missing Return: documentation Albu Victor-Marian
@ 2026-11-05  5:11 ` Dan Carpenter
  2026-11-05 20:21 ` [PATCH v2] " Albu Victor-Marian
  1 sibling, 0 replies; 7+ messages in thread
From: Dan Carpenter @ 2026-11-05  5:11 UTC (permalink / raw)
  To: Albu Victor-Marian
  Cc: parthiban.veerasooran, christian.gromm, gregkh, linux-staging,
	linux-kernel

On Wed, Nov 04, 2026 at 10:51:08PM +0200, Albu Victor-Marian wrote:
> Add missing Return: descriptions to functions in dim2.c. 
> 
> Signed-off-by: Albu Victor-Marian <albu.victor.m@gmail.com>
> ---
>  drivers/staging/most/dim2/dim2.c | 30 ++++++++++++++++++++++++++----
>  1 file changed, 26 insertions(+), 4 deletions(-)
> 
> diff --git a/drivers/staging/most/dim2/dim2.c b/drivers/staging/most/dim2/dim2.c
> index 0e2512d166329..7ed38d5d93f05 100644
> --- a/drivers/staging/most/dim2/dim2.c
> +++ b/drivers/staging/most/dim2/dim2.c
> @@ -156,6 +156,10 @@ void dimcb_on_error(u8 error_id, const char *error_message)
>   * @hdm_ch: channel specific data
>   *
>   * Transfer a buffer from pending_list if the channel is ready
> + *
> + * Return: 0 on success, -EINVAL if hdm_ch is not initialized, -EAGAIN if hdm_ch pending_list is
> + * empty, dim_channel is not ready or there is not enough DBR space, -EFAULT if first MBO bus
> + * address is 0 or dim_channel fails to start

These line lengths are too long.

Normally we would just say 0 on success and negative error codes on
failure.  Spelling them all out like this will be hard to keep in sync
 with the code.

regards,
dan carpenter


^ permalink raw reply	[flat|nested] 7+ messages in thread

* [PATCH v2] staging: most: dim2: add missing Return: documentation
  2026-11-04 20:51 [PATCH] staging: most: dim2: add missing Return: documentation Albu Victor-Marian
  2026-11-05  5:11 ` Dan Carpenter
@ 2026-11-05 20:21 ` Albu Victor-Marian
  2026-11-20  7:16   ` Greg KH
  1 sibling, 1 reply; 7+ messages in thread
From: Albu Victor-Marian @ 2026-11-05 20:21 UTC (permalink / raw)
  To: albu.victor.m, Dan Carpenter
  Cc: christian.gromm, gregkh, linux-kernel, linux-staging,
	parthiban.veerasooran

Add missing Return: descriptions to functions in dim2.c.

Signed-off-by: Albu Victor-Marian <albu.victor.m@gmail.com>
---
Changes in v2:
	* Simplified the Return: descriptions

	modified:   drivers/staging/most/dim2/dim2.c
---
 drivers/staging/most/dim2/dim2.c | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/drivers/staging/most/dim2/dim2.c b/drivers/staging/most/dim2/dim2.c
index 0e2512d166329..34c0eb796c291 100644
--- a/drivers/staging/most/dim2/dim2.c
+++ b/drivers/staging/most/dim2/dim2.c
@@ -156,6 +156,8 @@ void dimcb_on_error(u8 error_id, const char *error_message)
  * @hdm_ch: channel specific data
  *
  * Transfer a buffer from pending_list if the channel is ready
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int try_start_dim_transfer(struct hdm_channel *hdm_ch)
 {
@@ -211,6 +213,8 @@ static int try_start_dim_transfer(struct hdm_channel *hdm_ch)
  * @data: private data
  *
  * Wait for network status and deliver it to mostcore once it is received
+ *
+ * Return: 0 when the thread stops without error.
  */
 static int deliver_netinfo_thread(void *data)
 {
@@ -392,6 +396,9 @@ static irqreturn_t dim2_task_irq(int irq, void *_dev)
  *
  * Acknowledge the interrupt and service each initialized channel,
  * if needed, in task context.
+ *
+ * Return: IRQ_WAKE_THREAD after acknowledging the interrupt and
+ * servicing each initialized channel.
  */
 static irqreturn_t dim2_ahb_isr(int irq, void *_dev)
 {
@@ -442,7 +449,9 @@ static void complete_all_mbos(struct list_head *head)
  * @ccfg: structure that holds the configuration information
  *
  * Receives configuration information from mostcore and initialize
- * the corresponding channel. Return 0 on success, negative on failure.
+ * the corresponding channel.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int configure_channel(struct most_interface *most_iface, int ch_idx,
 			     struct most_channel_config *ccfg)
@@ -561,7 +570,9 @@ static int configure_channel(struct most_interface *most_iface, int ch_idx,
  * @mbo: pointer to the buffer object
  *
  * Push the buffer into pending_list and try to transfer one buffer from
- * pending_list. Return 0 on success, negative on failure.
+ * pending_list.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int enqueue(struct most_interface *most_iface, int ch_idx,
 		   struct mbo *mbo)
@@ -637,7 +648,9 @@ static void request_netinfo(struct most_interface *most_iface, int ch_idx,
  * @ch_idx: corresponding channel ID
  *
  * Destroy a channel and complete all the buffers in both started_list &
- * pending_list. Return 0 on success, negative on failure.
+ * pending_list.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int poison_channel(struct most_interface *most_iface, int ch_idx)
 {
@@ -710,6 +723,8 @@ static struct {
  *
  * By success stores one of the CLK_{NUMBER}FS in the *val and returns 0,
  * otherwise returns -EINVAL.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int get_dim2_clk_speed(const char *clock_speed, u8 *val)
 {
@@ -746,7 +761,8 @@ static void dim2_release(struct device *d)
  * @pdev: platform device structure
  *
  * Register the dim2 interface with mostcore and initialize it.
- * Return 0 on success, negative on failure.
+ *
+ * Return: 0 on success, negative on failure.
  */
 static int dim2_probe(struct platform_device *pdev)
 {
-- 
2.43.0


^ permalink raw reply related	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] staging: most: dim2: add missing Return: documentation
  2026-11-05 20:21 ` [PATCH v2] " Albu Victor-Marian
@ 2026-11-20  7:16   ` Greg KH
  2026-11-20 10:18     ` Victor-Marian Albu
  2026-11-20 11:44     ` Victor-Marian Albu
  0 siblings, 2 replies; 7+ messages in thread
From: Greg KH @ 2026-11-20  7:16 UTC (permalink / raw)
  To: Albu Victor-Marian
  Cc: Dan Carpenter, christian.gromm, linux-kernel, linux-staging,
	parthiban.veerasooran

On Thu, Nov 05, 2026 at 10:21:10PM +0200, Albu Victor-Marian wrote:
> Add missing Return: descriptions to functions in dim2.c.
> 

No, the descriptions are there, you just moved them around a bit.  And
why?  What needs this?

thanks,

greg k-h

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] staging: most: dim2: add missing Return: documentation
  2026-11-20  7:16   ` Greg KH
@ 2026-11-20 10:18     ` Victor-Marian Albu
  2026-11-20 10:22       ` Greg KH
  2026-11-20 11:44     ` Victor-Marian Albu
  1 sibling, 1 reply; 7+ messages in thread
From: Victor-Marian Albu @ 2026-11-20 10:18 UTC (permalink / raw)
  To: Greg KH
  Cc: Dan Carpenter, christian.gromm, linux-kernel, linux-staging,
	parthiban.veerasooran

A few had no Return: at all so I added one, the others already had the
sentence and I moved it into a Return: section, because kernel-doc
-Wall only looks for that. Nothing needs this, drop it if it's not
useful.

thanks,

Albu Victor-Marian

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] staging: most: dim2: add missing Return: documentation
  2026-11-20 10:18     ` Victor-Marian Albu
@ 2026-11-20 10:22       ` Greg KH
  0 siblings, 0 replies; 7+ messages in thread
From: Greg KH @ 2026-11-20 10:22 UTC (permalink / raw)
  To: Victor-Marian Albu
  Cc: Dan Carpenter, christian.gromm, linux-kernel, linux-staging,
	parthiban.veerasooran

On Fri, Nov 20, 2026 at 12:18:09PM +0200, Victor-Marian Albu wrote:
> A few had no Return: at all so I added one, the others already had the
> sentence and I moved it into a Return: section, because kernel-doc
> -Wall only looks for that. Nothing needs this, drop it if it's not
> useful.

I have no context here at all, sorry.

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: [PATCH v2] staging: most: dim2: add missing Return: documentation
  2026-11-20  7:16   ` Greg KH
  2026-11-20 10:18     ` Victor-Marian Albu
@ 2026-11-20 11:44     ` Victor-Marian Albu
  1 sibling, 0 replies; 7+ messages in thread
From: Victor-Marian Albu @ 2026-11-20 11:44 UTC (permalink / raw)
  To: Greg Kroah-Hartman
  Cc: Dan Carpenter, christian.gromm, linux-kernel, linux-staging,
	parthiban.veerasooran

I added a Return: section to every function that kernel-doc -Wall
flagged. For some of them the comment already described the return
value in a sentence, so the information was there, but kernel-doc only
counts a Return: section, which is why I added it. Nothing needs this.
Let me know if you’d like it changed.

Patch: https://lore.kernel.org/linux-staging/20261104205108.1041666-1-albu.victor.m@gmail.com/

thanks,
Albu Victor-Marian

On FRI, NOV 20, 2026 la 09:16, Greg KH <gregkh@linuxfoundation.org> wrote:
>
> On Thu, Nov 05, 2026 at 10:21:10PM +0200, Albu Victor-Marian wrote:
> > Add missing Return: descriptions to functions in dim2.c.
> >
>
> No, the descriptions are there, you just moved them around a bit.  And
> why?  What needs this?
>
> thanks,
>
> greg k-h

^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2026-11-20 11:44 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-04 20:51 [PATCH] staging: most: dim2: add missing Return: documentation Albu Victor-Marian
2026-11-05  5:11 ` Dan Carpenter
2026-11-05 20:21 ` [PATCH v2] " Albu Victor-Marian
2026-11-20  7:16   ` Greg KH
2026-11-20 10:18     ` Victor-Marian Albu
2026-11-20 10:22       ` Greg KH
2026-11-20 11:44     ` Victor-Marian Albu

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.