lkml.org 
[lkml]   [2022]   [Nov]   [23]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[patch V3 16/17] timers: Update the documentation to reflect on the new timer_shutdown() API
    Date
    From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

    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 updated the zh_CN version ]

    Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
    Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
    Tested-by: Guenter Roeck <linux@roeck-us.net>
    Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
    Link: https://lore.kernel.org/r/20221110064147.712934793@goodmis.org
    ---
    Documentation/RCU/Design/Requirements/Requirements.rst | 2 +-
    Documentation/core-api/local_ops.rst | 2 +-
    Documentation/kernel-hacking/locking.rst | 5 +++++
    Documentation/translations/zh_CN/core-api/local_ops.rst | 2 +-
    4 files changed, 8 insertions(+), 3 deletions(-)

    --- 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 timer_delete_sync() or similar.
    +with via timer_shutdown_sync() or similar.

    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)
    {
    - timer_delete_sync(&test_timer);
    + timer_shutdown_sync(&test_timer);
    }

    module_init(test_init);
    --- a/Documentation/kernel-hacking/locking.rst
    +++ b/Documentation/kernel-hacking/locking.rst
    @@ -1007,6 +1007,11 @@ calling add_timer() at the end of their
    Because this is a fairly common case which is prone to races, you should
    use timer_delete_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
    =============

    --- a/Documentation/translations/zh_CN/core-api/local_ops.rst
    +++ b/Documentation/translations/zh_CN/core-api/local_ops.rst
    @@ -185,7 +185,7 @@ UP之间没有不同的行为,在你�

    static void __exit test_exit(void)
    {
    - timer_delete_sync(&test_timer);
    + timer_shutdown_sync(&test_timer);
    }

    module_init(test_init);
    \
     
     \ /
      Last update: 2022-11-23 21:22    [W:3.517 / U:0.600 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site