mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
synced 2025-01-01 10:42:11 +00:00
89124747f0
Function descriptions in iopoll.h, regmap.h, phy.h and sound/soc/sof/ops.h copied all the same outdated documentation about sleep/delay function limitations. In those comments, the generic (and still outdated) timer documentation file is referenced. As proper function descriptions for used delay and sleep functions are in place, simply update the descriptions to reference to them. While at it fix missing colon after "Returns" in function description and move return value description to the end of the function description. Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de> Signed-off-by: Thomas Gleixner <tglx@linutronix.de> Reviewed-by: Andrew Lunn <andrew@lunn.ch> # for phy.h Reviewed-by: Frederic Weisbecker <frederic@kernel.org> Link: https://lore.kernel.org/all/20241014-devel-anna-maria-b4-timers-flseep-v3-12-dc8b907cb62f@linutronix.de
206 lines
7.9 KiB
C
206 lines
7.9 KiB
C
/* SPDX-License-Identifier: GPL-2.0-only */
|
|
/*
|
|
* Copyright (c) 2012-2014 The Linux Foundation. All rights reserved.
|
|
*/
|
|
|
|
#ifndef _LINUX_IOPOLL_H
|
|
#define _LINUX_IOPOLL_H
|
|
|
|
#include <linux/kernel.h>
|
|
#include <linux/types.h>
|
|
#include <linux/ktime.h>
|
|
#include <linux/delay.h>
|
|
#include <linux/errno.h>
|
|
#include <linux/io.h>
|
|
|
|
/**
|
|
* read_poll_timeout - Periodically poll an address until a condition is
|
|
* met or a timeout occurs
|
|
* @op: accessor function (takes @args as its arguments)
|
|
* @val: Variable to read the value into
|
|
* @cond: Break condition (usually involving @val)
|
|
* @sleep_us: Maximum time to sleep between reads in us (0 tight-loops). Please
|
|
* read usleep_range() function description for details and
|
|
* limitations.
|
|
* @timeout_us: Timeout in us, 0 means never timeout
|
|
* @sleep_before_read: if it is true, sleep @sleep_us before read.
|
|
* @args: arguments for @op poll
|
|
*
|
|
* When available, you'll probably want to use one of the specialized
|
|
* macros defined below rather than this macro directly.
|
|
*
|
|
* Returns: 0 on success and -ETIMEDOUT upon a timeout. In either
|
|
* case, the last read value at @args is stored in @val. Must not
|
|
* be called from atomic context if sleep_us or timeout_us are used.
|
|
*/
|
|
#define read_poll_timeout(op, val, cond, sleep_us, timeout_us, \
|
|
sleep_before_read, args...) \
|
|
({ \
|
|
u64 __timeout_us = (timeout_us); \
|
|
unsigned long __sleep_us = (sleep_us); \
|
|
ktime_t __timeout = ktime_add_us(ktime_get(), __timeout_us); \
|
|
might_sleep_if((__sleep_us) != 0); \
|
|
if (sleep_before_read && __sleep_us) \
|
|
usleep_range((__sleep_us >> 2) + 1, __sleep_us); \
|
|
for (;;) { \
|
|
(val) = op(args); \
|
|
if (cond) \
|
|
break; \
|
|
if (__timeout_us && \
|
|
ktime_compare(ktime_get(), __timeout) > 0) { \
|
|
(val) = op(args); \
|
|
break; \
|
|
} \
|
|
if (__sleep_us) \
|
|
usleep_range((__sleep_us >> 2) + 1, __sleep_us); \
|
|
cpu_relax(); \
|
|
} \
|
|
(cond) ? 0 : -ETIMEDOUT; \
|
|
})
|
|
|
|
/**
|
|
* read_poll_timeout_atomic - Periodically poll an address until a condition is
|
|
* met or a timeout occurs
|
|
* @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
|
|
* 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.
|
|
* @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.
|
|
*
|
|
* When available, you'll probably want to use one of the specialized
|
|
* macros defined below rather than this macro directly.
|
|
*
|
|
* Returns: 0 on success and -ETIMEDOUT upon a timeout. In either
|
|
* case, the last read value at @args is stored in @val.
|
|
*/
|
|
#define read_poll_timeout_atomic(op, val, cond, delay_us, timeout_us, \
|
|
delay_before_read, args...) \
|
|
({ \
|
|
u64 __timeout_us = (timeout_us); \
|
|
s64 __left_ns = __timeout_us * NSEC_PER_USEC; \
|
|
unsigned long __delay_us = (delay_us); \
|
|
u64 __delay_ns = __delay_us * NSEC_PER_USEC; \
|
|
if (delay_before_read && __delay_us) { \
|
|
udelay(__delay_us); \
|
|
if (__timeout_us) \
|
|
__left_ns -= __delay_ns; \
|
|
} \
|
|
for (;;) { \
|
|
(val) = op(args); \
|
|
if (cond) \
|
|
break; \
|
|
if (__timeout_us && __left_ns < 0) { \
|
|
(val) = op(args); \
|
|
break; \
|
|
} \
|
|
if (__delay_us) { \
|
|
udelay(__delay_us); \
|
|
if (__timeout_us) \
|
|
__left_ns -= __delay_ns; \
|
|
} \
|
|
cpu_relax(); \
|
|
if (__timeout_us) \
|
|
__left_ns--; \
|
|
} \
|
|
(cond) ? 0 : -ETIMEDOUT; \
|
|
})
|
|
|
|
/**
|
|
* readx_poll_timeout - Periodically poll an address until a condition is met or a timeout occurs
|
|
* @op: accessor function (takes @addr as its only argument)
|
|
* @addr: Address to poll
|
|
* @val: Variable to read the value into
|
|
* @cond: Break condition (usually involving @val)
|
|
* @sleep_us: Maximum time to sleep between reads in us (0 tight-loops). Please
|
|
* read usleep_range() function description for details and
|
|
* limitations.
|
|
* @timeout_us: Timeout in us, 0 means never timeout
|
|
*
|
|
* When available, you'll probably want to use one of the specialized
|
|
* macros defined below rather than this macro directly.
|
|
*
|
|
* Returns: 0 on success and -ETIMEDOUT upon a timeout. In either
|
|
* case, the last read value at @addr is stored in @val. Must not
|
|
* be called from atomic context if sleep_us or timeout_us are used.
|
|
*/
|
|
#define readx_poll_timeout(op, addr, val, cond, sleep_us, timeout_us) \
|
|
read_poll_timeout(op, val, cond, sleep_us, timeout_us, false, addr)
|
|
|
|
/**
|
|
* readx_poll_timeout_atomic - Periodically poll an address until a condition is met or a timeout occurs
|
|
* @op: accessor function (takes @addr as its only argument)
|
|
* @addr: Address to poll
|
|
* @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
|
|
* read udelay() function description for details and
|
|
* limitations.
|
|
* @timeout_us: Timeout in us, 0 means never timeout
|
|
*
|
|
* When available, you'll probably want to use one of the specialized
|
|
* macros defined below rather than this macro directly.
|
|
*
|
|
* Returns: 0 on success and -ETIMEDOUT upon a timeout. In either
|
|
* case, the last read value at @addr is stored in @val.
|
|
*/
|
|
#define readx_poll_timeout_atomic(op, addr, val, cond, delay_us, timeout_us) \
|
|
read_poll_timeout_atomic(op, val, cond, delay_us, timeout_us, false, addr)
|
|
|
|
#define readb_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readb, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readb_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readb, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readw_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readw, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readw_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readw, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readl_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readl, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readl_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readl, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readq_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readq, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readq_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readq, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readb_relaxed_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readb_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readb_relaxed_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readb_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readw_relaxed_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readw_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readw_relaxed_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readw_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readl_relaxed_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readl_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readl_relaxed_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readl_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readq_relaxed_poll_timeout(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout(readq_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#define readq_relaxed_poll_timeout_atomic(addr, val, cond, delay_us, timeout_us) \
|
|
readx_poll_timeout_atomic(readq_relaxed, addr, val, cond, delay_us, timeout_us)
|
|
|
|
#endif /* _LINUX_IOPOLL_H */
|