[14/15] timers: Update the documentation to reflect on the new timer_shutdown() API

Commit Message

Thomas Gleixner Nov. 15, 2022, 8:28 p.m. UTC

From: "Steven Rostedt (Google)" <[e-mail]>

In order to make sure that a timer is not re-armed after it is stopped
before freeing, a new shutdown state is added to the timer code. The API
timer_shutdown_sync() and timer_shutdown() must be called before the
object that holds the timer can be freed.

Update the documentation to reflect this new workflow.

[ tglx: Updated to the new semantics and removed the bogus claim that
  	del_timer_sync() returns the number of removal attempts ]

Signed-off-by: Steven Rostedt (Google) <[e-mail]>
Signed-off-by: Thomas Gleixner <[e-mail]>
Tested-by: Guenter Roeck <[e-mail]>
Link: https://lore.kernel.org/r/[e-mail]
---
 Documentation/RCU/Design/Requirements/Requirements.rst |    2 +-
 Documentation/core-api/local_ops.rst                   |    2 +-
 Documentation/kernel-hacking/locking.rst               |   13 ++++++++-----
 3 files changed, 10 insertions(+), 7 deletions(-)

Patch

--- a/Documentation/RCU/Design/Requirements/Requirements.rst
+++ b/Documentation/RCU/Design/Requirements/Requirements.rst
@@ -1858,7 +1858,7 @@  unloaded. After a given module has been
 one of its functions results in a segmentation fault. The module-unload
 functions must therefore cancel any delayed calls to loadable-module
 functions, for example, any outstanding mod_timer() must be dealt
-with via del_timer_sync() or similar.
+with via timer_shutdown_sync().
 
 Unfortunately, there is no way to cancel an RCU callback; once you
 invoke call_rcu(), the callback function is eventually going to be
--- a/Documentation/core-api/local_ops.rst
+++ b/Documentation/core-api/local_ops.rst
@@ -191,7 +191,7 @@  Here is a sample module which implements
 
     static void __exit test_exit(void)
     {
-            del_timer_sync(&test_timer);
+            timer_shutdown_sync(&test_timer);
     }
 
     module_init(test_init);
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -1003,11 +1003,14 @@  If 0, it means (in this case) that it is
 
 
 Another common problem is deleting timers which restart themselves (by
-calling add_timer() at the end of their timer function).
-Because this is a fairly common case which is prone to races, you should
-use del_timer_sync() (``include/linux/timer.h``) to
-handle this case. It returns the number of times the timer had to be
-deleted before we finally stopped it from adding itself back in.
+calling add_timer() at the end of their timer function).  Because this is a
+fairly common case which is prone to races, you should use del_timer_sync()
+(``include/linux/timer.h``) to handle this case.
+
+Before freeing a timer, timer_shutdown() or timer_shutdown_sync() should be
+called which will keep it from being rearmed. Any subsequent attempt to
+rearm the timer will be silently ignored by the core code.
+
 
 Locking Speed
 =============