[PATCH RESEND] iopoll: fix parameter names in kernel-doc

[PATCH RESEND] iopoll: fix parameter names in kernel-doc

[Randy Dunlap]

Correct the parameter names to avoid kernel-doc warnings:

Warning: include/linux/iopoll.h:169 function parameter 'sleep_us' not
 described in 'read_poll_timeout_atomic'
Warning: ../include/linux/iopoll.h:169 function parameter
 'sleep_before_read' not described in 'read_poll_timeout_atomic'

Fixes: 9df8043a546d ("iopoll: Generalize read_poll_timeout() into poll_timeout_us()")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
---
Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: intel-gfx@lists.freedesktop.org
Cc: intel-xe@lists.freedesktop.org
---
 include/linux/iopoll.h |    6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

--- linux-next-20260304.orig/include/linux/iopoll.h
+++ linux-next-20260304/include/linux/iopoll.h
@@ -150,16 +150,16 @@
  * @op: accessor function (takes @args as its arguments)
  * @val: Variable to read the value into
  * @cond: Break condition (usually involving @val)
- * @delay_us: Time to udelay between reads in us (0 tight-loops). Please
+ * @sleep_us: Time to udelay between reads in us (0 tight-loops). Please
  *            read udelay() function description for details and
  *            limitations.
  * @timeout_us: Timeout in us, 0 means never timeout
- * @delay_before_read: if it is true, delay @delay_us before read.
+ * @sleep_before_read: if it is true, delay @sleep_us before read.
  * @args: arguments for @op poll
  *
  * This macro does not rely on timekeeping.  Hence it is safe to call even when
  * timekeeping is suspended, at the expense of an underestimation of wall clock
- * time, which is rather minimal with a non-zero delay_us.
+ * time, which is rather minimal with a non-zero @sleep_us.
  *
  * When available, you'll probably want to use one of the specialized
  * macros defined below rather than this macro directly.

Re: [PATCH RESEND] iopoll: fix parameter names in kernel-doc

[Jani Nikula]

On Thu, 05 Mar 2026, Randy Dunlap <rdunlap@infradead.org> wrote:
> Correct the parameter names to avoid kernel-doc warnings:
>
> Warning: include/linux/iopoll.h:169 function parameter 'sleep_us' not
>  described in 'read_poll_timeout_atomic'
> Warning: ../include/linux/iopoll.h:169 function parameter
>  'sleep_before_read' not described in 'read_poll_timeout_atomic'

I think the right fix is to rename the parameters instead. They're
passed on to poll_timeout_us_atomic() where the parameters are called
delay_us and delay_before_op, emphasizing that this is atomic i.e. no
sleep.

BR,
Jani.

>
> Fixes: 9df8043a546d ("iopoll: Generalize read_poll_timeout() into poll_timeout_us()")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> ---
> Cc: Ville Syrjälä <ville.syrjala@linux.intel.com>
> Cc: Jani Nikula <jani.nikula@intel.com>
> Cc: intel-gfx@lists.freedesktop.org
> Cc: intel-xe@lists.freedesktop.org
> ---
>  include/linux/iopoll.h |    6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> --- linux-next-20260304.orig/include/linux/iopoll.h
> +++ linux-next-20260304/include/linux/iopoll.h
> @@ -150,16 +150,16 @@
>   * @op: accessor function (takes @args as its arguments)
>   * @val: Variable to read the value into
>   * @cond: Break condition (usually involving @val)
> - * @delay_us: Time to udelay between reads in us (0 tight-loops). Please
> + * @sleep_us: Time to udelay between reads in us (0 tight-loops). Please
>   *            read udelay() function description for details and
>   *            limitations.
>   * @timeout_us: Timeout in us, 0 means never timeout
> - * @delay_before_read: if it is true, delay @delay_us before read.
> + * @sleep_before_read: if it is true, delay @sleep_us before read.
>   * @args: arguments for @op poll
>   *
>   * This macro does not rely on timekeeping.  Hence it is safe to call even when
>   * timekeeping is suspended, at the expense of an underestimation of wall clock
> - * time, which is rather minimal with a non-zero delay_us.
> + * time, which is rather minimal with a non-zero @sleep_us.
>   *
>   * When available, you'll probably want to use one of the specialized
>   * macros defined below rather than this macro directly.

-- 
Jani Nikula, Intel

Re: [PATCH RESEND] iopoll: fix parameter names in kernel-doc

[Randy Dunlap]

On 3/6/26 2:31 AM, Jani Nikula wrote:
> On Thu, 05 Mar 2026, Randy Dunlap <rdunlap@infradead.org> wrote:
>> Correct the parameter names to avoid kernel-doc warnings:
>>
>> Warning: include/linux/iopoll.h:169 function parameter 'sleep_us' not
>>  described in 'read_poll_timeout_atomic'
>> Warning: ../include/linux/iopoll.h:169 function parameter
>>  'sleep_before_read' not described in 'read_poll_timeout_atomic'
> 
> I think the right fix is to rename the parameters instead. They're
> passed on to poll_timeout_us_atomic() where the parameters are called
> delay_us and delay_before_op, emphasizing that this is atomic i.e. no
> sleep.

OK, will do.
Thanks.

-- 
~Randy