[PATCH 00/15] timers: Cleanup delay/sleep related mess

[PATCH 00/15] timers: Cleanup delay/sleep related mess

[Anna-Maria Behnsen]

Hi,

a question about which sleeping function should be used in acpi_os_sleep()
started a discussion and examination about the existing documentation and
implementation of functions which insert a sleep/delay.

The result of the discussion was, that the documentation is outdated and
the implemented fsleep() reflects the outdated documentation but doesn't
help to reflect reality which in turns leads to the queue which covers the
following things:

- Minor changes (naming and typo fixes)

- Split out all timeout and sleep related functions from hrtimer.c and timer.c
  into a separate file

- Update function descriptions of sleep related functions

- Change fsleep() to reflect reality

- Rework all comments or users which obviously rely on the outdated
  documentation as they reference "Documentation/timers/timers-howto.rst"

- Last but not least (as there are no more references): Update the outdated
  documentation and move it into a file with a self explaining file name

The queue is available here and applies on top of tip/timers/core:

  git://git.kernel.org/pub/scm/linux/kernel/git/anna-maria/linux-devel.git timers/misc

Cc: linux-kernel@vger.kernel.org
Cc: Len Brown <len.brown@intel.com>
Cc: Rafael J. Wysocki <rafael@kernel.org>
To: Frederic Weisbecker <frederic@kernel.org>
To: Thomas Gleixner <tglx@linutronix.de>
To: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>

Thanks,

Anna-Maria

---
Anna-Maria Behnsen (15):
      timers: Rename next_expiry_recalc() to be unique
      cpu: Use already existing usleep_range()
      Comments: Fix wrong singular form of jiffies
      timers: Move *sleep*() and timeout functions into a separate file
      timers: Rename sleep_idle_range() to sleep_range_idle()
      timers: Update function descriptions of sleep/delay related functions
      timers: Adjust flseep() to reflect reality
      mm/damon/core: Use generic upper bound recommondation for usleep_range()
      timers: Add a warning to usleep_range_state() for wrong order of arguments
      checkpatch: Remove broken sleep/delay related checks
      regulator: core: Use fsleep() to get best sleep mechanism
      iopoll/regmap/phy/snd: Fix comment referencing outdated timer documentation
      powerpc/rtas: Use fsleep() to minimize additional sleep duration
      media: anysee: Fix link to outdated sleep function documentation
      timers/Documentation: Cleanup delay/sleep documentation

 Documentation/admin-guide/media/vivid.rst          |   2 +-
 Documentation/dev-tools/checkpatch.rst             |   6 -
 Documentation/timers/delay_sleep_functions.rst     | 122 +++++++
 Documentation/timers/index.rst                     |   2 +-
 Documentation/timers/timers-howto.rst              | 115 -------
 .../sp_SP/scheduler/sched-design-CFS.rst           |   2 +-
 MAINTAINERS                                        |   2 +
 arch/arm/mach-versatile/spc.c                      |   2 +-
 arch/m68k/q40/q40ints.c                            |   2 +-
 arch/powerpc/kernel/rtas.c                         |  21 +-
 arch/x86/kernel/cpu/mce/dev-mcelog.c               |   2 +-
 drivers/char/ipmi/ipmi_ssif.c                      |   2 +-
 drivers/dma-buf/st-dma-fence.c                     |   2 +-
 drivers/gpu/drm/i915/gem/i915_gem_wait.c           |   2 +-
 drivers/gpu/drm/i915/gt/selftest_execlists.c       |   4 +-
 drivers/gpu/drm/i915/i915_utils.c                  |   2 +-
 drivers/gpu/drm/v3d/v3d_bo.c                       |   2 +-
 drivers/isdn/mISDN/dsp_cmx.c                       |   2 +-
 drivers/media/usb/dvb-usb-v2/anysee.c              |   6 +-
 drivers/net/ethernet/marvell/mvmdio.c              |   2 +-
 drivers/regulator/core.c                           |  33 +-
 fs/xfs/xfs_buf.h                                   |   2 +-
 include/asm-generic/delay.h                        |  46 ++-
 include/linux/delay.h                              |  79 ++++-
 include/linux/iopoll.h                             |  24 +-
 include/linux/jiffies.h                            |   2 +-
 include/linux/phy.h                                |   7 +-
 include/linux/regmap.h                             |  18 +-
 include/linux/timekeeper_internal.h                |   2 +-
 kernel/cpu.c                                       |   2 +-
 kernel/time/Makefile                               |   2 +-
 kernel/time/alarmtimer.c                           |   2 +-
 kernel/time/clockevents.c                          |   2 +-
 kernel/time/hrtimer.c                              | 122 +------
 kernel/time/posix-timers.c                         |   4 +-
 kernel/time/sleep_timeout.c                        | 363 +++++++++++++++++++++
 kernel/time/timer.c                                | 210 +-----------
 lib/Kconfig.debug                                  |   2 +-
 mm/damon/core.c                                    |   5 +-
 net/batman-adv/types.h                             |   2 +-
 scripts/checkpatch.pl                              |  38 ---
 sound/soc/sof/ops.h                                |   6 +-
 42 files changed, 668 insertions(+), 607 deletions(-)

[PATCH 12/15] iopoll/regmap/phy/snd: Fix comment referencing outdated timer documentation

[Anna-Maria Behnsen]

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.

Cc: Andrew Lunn <andrew@lunn.ch>
Cc: Heiner Kallweit <hkallweit1@gmail.com>
Cc: Jaroslav Kysela <perex@perex.cz>
Cc: Takashi Iwai <tiwai@suse.com>
Cc: netdev@vger.kernel.org
Cc: linux-sound@vger.kernel.org
Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
---
 include/linux/iopoll.h | 24 ++++++++++++------------
 include/linux/phy.h    |  7 ++++---
 include/linux/regmap.h | 18 +++++++++---------
 sound/soc/sof/ops.h    |  6 +++---
 4 files changed, 28 insertions(+), 27 deletions(-)

diff --git a/include/linux/iopoll.h b/include/linux/iopoll.h
index 19a7b00baff4..34b52ab2e394 100644
--- a/include/linux/iopoll.h
+++ b/include/linux/iopoll.h
@@ -19,9 +19,9 @@
  * @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).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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
@@ -64,9 +64,9 @@
  * @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).  Should
- *            be less than ~10us since udelay is used (see
- *            Documentation/timers/timers-howto.rst).
+ * @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
@@ -119,9 +119,9 @@
  * @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).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout. In either
@@ -140,9 +140,9 @@
  * @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).  Should
- *            be less than ~10us since udelay is used (see
- *            Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout. In either
diff --git a/include/linux/phy.h b/include/linux/phy.h
index 6b7d40d49129..b09490e08365 100644
--- a/include/linux/phy.h
+++ b/include/linux/phy.h
@@ -1374,11 +1374,12 @@ int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
  * @regnum: The register on the MMD to read
  * @val: Variable to read the register into
  * @cond: Break condition (usually involving @val)
- * @sleep_us: Maximum time to sleep between reads in us (0
- *            tight-loops).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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.
+ *
  * 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.
diff --git a/include/linux/regmap.h b/include/linux/regmap.h
index 122e38161acb..85de129a9e02 100644
--- a/include/linux/regmap.h
+++ b/include/linux/regmap.h
@@ -106,9 +106,9 @@ struct reg_sequence {
  * @addr: Address to poll
  * @val: Unsigned integer 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).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
@@ -133,9 +133,9 @@ struct reg_sequence {
  * @addr: Address to poll
  * @val: Unsigned integer variable to read the value into
  * @cond: Break condition (usually involving @val)
- * @delay_us: Time to udelay between reads in us (0 tight-loops).
- *            Should be less than ~10us since udelay is used
- *            (see Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_read
@@ -177,9 +177,9 @@ struct reg_sequence {
  * @field: Regmap field to read from
  * @val: Unsigned integer 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).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout or the regmap_field_read
diff --git a/sound/soc/sof/ops.h b/sound/soc/sof/ops.h
index 2584621c3b2d..b1b8253aefad 100644
--- a/sound/soc/sof/ops.h
+++ b/sound/soc/sof/ops.h
@@ -597,9 +597,9 @@ snd_sof_is_chain_dma_supported(struct snd_sof_dev *sdev, u32 dai_type)
  * @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).  Should be less than ~20ms since usleep_range
- *            is used (see Documentation/timers/timers-howto.rst).
+ * @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
  *
  * Returns 0 on success and -ETIMEDOUT upon a timeout. In either

-- 
2.39.2

Re: [PATCH 12/15] iopoll/regmap/phy/snd: Fix comment referencing outdated timer documentation

[Andrew Lunn]

> diff --git a/include/linux/phy.h b/include/linux/phy.h
> index 6b7d40d49129..b09490e08365 100644
> --- a/include/linux/phy.h
> +++ b/include/linux/phy.h
> @@ -1374,11 +1374,12 @@ int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
>   * @regnum: The register on the MMD to read
>   * @val: Variable to read the register into
>   * @cond: Break condition (usually involving @val)
> - * @sleep_us: Maximum time to sleep between reads in us (0
> - *            tight-loops).  Should be less than ~20ms since usleep_range
> - *            is used (see Documentation/timers/timers-howto.rst).
> + * @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.
> + *
>   * Returns 0 on success and -ETIMEDOUT upon a timeout. In either

I know it is not in scope for what you are trying to fix, but there
should be a : after Returns

* Returns: 0 on success and -ETIMEDOUT upon a timeout. In either

Reviewed-by: Andrew Lunn <andrew@lunn.ch>

    Andrew

Re: [PATCH 00/15] timers: Cleanup delay/sleep related mess

[Rafael J. Wysocki]

On Wed, Sep 4, 2024 at 3:05 PM Anna-Maria Behnsen
<anna-maria@linutronix.de> wrote:
>
> Hi,
>
> a question about which sleeping function should be used in acpi_os_sleep()
> started a discussion and examination about the existing documentation and
> implementation of functions which insert a sleep/delay.
>
> The result of the discussion was, that the documentation is outdated and
> the implemented fsleep() reflects the outdated documentation but doesn't
> help to reflect reality which in turns leads to the queue which covers the
> following things:
>
> - Minor changes (naming and typo fixes)
>
> - Split out all timeout and sleep related functions from hrtimer.c and timer.c
>   into a separate file
>
> - Update function descriptions of sleep related functions
>
> - Change fsleep() to reflect reality
>
> - Rework all comments or users which obviously rely on the outdated
>   documentation as they reference "Documentation/timers/timers-howto.rst"
>
> - Last but not least (as there are no more references): Update the outdated
>   documentation and move it into a file with a self explaining file name
>
> The queue is available here and applies on top of tip/timers/core:
>
>   git://git.kernel.org/pub/scm/linux/kernel/git/anna-maria/linux-devel.git timers/misc
>
> Cc: linux-kernel@vger.kernel.org
> Cc: Len Brown <len.brown@intel.com>
> Cc: Rafael J. Wysocki <rafael@kernel.org>
> To: Frederic Weisbecker <frederic@kernel.org>
> To: Thomas Gleixner <tglx@linutronix.de>
> To: Jonathan Corbet <corbet@lwn.net>
> Signed-off-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
>
> Thanks,
>
> Anna-Maria
>
> ---
> Anna-Maria Behnsen (15):
>       timers: Rename next_expiry_recalc() to be unique
>       cpu: Use already existing usleep_range()
>       Comments: Fix wrong singular form of jiffies
>       timers: Move *sleep*() and timeout functions into a separate file
>       timers: Rename sleep_idle_range() to sleep_range_idle()
>       timers: Update function descriptions of sleep/delay related functions
>       timers: Adjust flseep() to reflect reality
>       mm/damon/core: Use generic upper bound recommondation for usleep_range()
>       timers: Add a warning to usleep_range_state() for wrong order of arguments
>       checkpatch: Remove broken sleep/delay related checks
>       regulator: core: Use fsleep() to get best sleep mechanism
>       iopoll/regmap/phy/snd: Fix comment referencing outdated timer documentation
>       powerpc/rtas: Use fsleep() to minimize additional sleep duration
>       media: anysee: Fix link to outdated sleep function documentation
>       timers/Documentation: Cleanup delay/sleep documentation

I like the changes, so

Acked-by: Rafael J. Wysocki <rafael@kernel.org>

for the series.

Re: [PATCH 12/15] iopoll/regmap/phy/snd: Fix comment referencing outdated timer documentation

[Anna-Maria Behnsen]

Andrew Lunn <andrew@lunn.ch> writes:

>> diff --git a/include/linux/phy.h b/include/linux/phy.h
>> index 6b7d40d49129..b09490e08365 100644
>> --- a/include/linux/phy.h
>> +++ b/include/linux/phy.h
>> @@ -1374,11 +1374,12 @@ int phy_read_mmd(struct phy_device *phydev, int devad, u32 regnum);
>>   * @regnum: The register on the MMD to read
>>   * @val: Variable to read the register into
>>   * @cond: Break condition (usually involving @val)
>> - * @sleep_us: Maximum time to sleep between reads in us (0
>> - *            tight-loops).  Should be less than ~20ms since usleep_range
>> - *            is used (see Documentation/timers/timers-howto.rst).
>> + * @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.
>> + *
>>   * Returns 0 on success and -ETIMEDOUT upon a timeout. In either
>
> I know it is not in scope for what you are trying to fix, but there
> should be a : after Returns
>
> * Returns: 0 on success and -ETIMEDOUT upon a timeout. In either

I have to do a v2 of the series anyway. So if it helps, I can add the
missing colon after "Returns" in all those function descriptions I touch
and expand the commit message by:

  While at it fix missing colon after "Returns" in function description
  as well.

> Reviewed-by: Andrew Lunn <andrew@lunn.ch>
>
>     Andrew

Thanks,

        Anna-Maria

Re: (subset) [PATCH 00/15] timers: Cleanup delay/sleep related mess

[Mark Brown]

On Wed, 04 Sep 2024 15:04:50 +0200, Anna-Maria Behnsen wrote:
> a question about which sleeping function should be used in acpi_os_sleep()
> started a discussion and examination about the existing documentation and
> implementation of functions which insert a sleep/delay.
> 
> The result of the discussion was, that the documentation is outdated and
> the implemented fsleep() reflects the outdated documentation but doesn't
> help to reflect reality which in turns leads to the queue which covers the
> following things:
> 
> [...]

Applied to

   https://git.kernel.org/pub/scm/linux/kernel/git/broonie/regulator.git for-next

Thanks!

[11/15] regulator: core: Use fsleep() to get best sleep mechanism
        commit: f20669fbcf99d0e15e94fb50929bb1c41618e197

All being well this means that it will be integrated into the linux-next
tree (usually sometime in the next 24 hours) and sent to Linus during
the next merge window (or sooner if it is a bug fix), however if
problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing
and review of the tree, please engage with people reporting problems and
send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they
should be sent as incremental updates against current git, existing
patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying
to this mail.

Thanks,
Mark