Commit 28ef2db8 authored by Peter Xu's avatar Peter Xu Committed by Thomas Gleixner
Browse files

timer: Document TIMER_PINNED 



The flag hints the user that the pinned timers will always be run on a
static CPU (because that should be what "pinned" means...) but that's
not the truth, at least with the current implementation.

For example, currently if a pinned timer is set up but later mod_timer()
upon the pinned timer is invoked, mod_timer() will still try to queue the
timer on the current processor and migrate the timer if necessary.

Document it a bit with the definition of TIMER_PINNED so that all future
users will use it correctly.

Signed-off-by: default avatarPeter Xu <peterx@redhat.com>
Signed-off-by: default avatarThomas Gleixner <tglx@linutronix.de>
Cc: Marcelo Tosatti <mtosatti@redhat.com>
Cc: Luiz Capitulino <lcapitulino@redhat.com>
Link: https://lkml.kernel.org/r/20190628105942.14131-1-peterx@redhat.com
parent dd2cb348

include/linux/timer.h

+19 −8
Original line number Diff line number Diff line
@@ -36,19 +36,30 @@ struct timer_list { 
#define __TIMER_LOCKDEP_MAP_INITIALIZER(_kn)

#endif



/*

 * A deferrable timer will work normally when the system is busy, but

 * will not cause a CPU to come out of idle just to service it; instead,

 * the timer will be serviced when the CPU eventually wakes up with a

 * subsequent non-deferrable timer.

/**

 * @TIMER_DEFERRABLE: A deferrable timer will work normally when the

 * system is busy, but will not cause a CPU to come out of idle just

 * to service it; instead, the timer will be serviced when the CPU

 * eventually wakes up with a subsequent non-deferrable timer.

 *

 * An irqsafe timer is executed with IRQ disabled and it's safe to wait for

 * the completion of the running instance from IRQ handlers, for example,

 * by calling del_timer_sync().

 * @TIMER_IRQSAFE: An irqsafe timer is executed with IRQ disabled and

 * it's safe to wait for the completion of the running instance from

 * IRQ handlers, for example, by calling del_timer_sync().

 *

 * Note: The irq disabled callback execution is a special case for

 * workqueue locking issues. It's not meant for executing random crap

 * with interrupts disabled. Abuse is monitored!

 *

 * @TIMER_PINNED: A pinned timer will not be affected by any timer

 * placement heuristics (like, NOHZ) and will always expire on the CPU

 * on which the timer was enqueued.

 *

 * Note: Because enqueuing of timers can migrate the timer from one

 * CPU to another, pinned timers are not guaranteed to stay on the

 * initialy selected CPU.  They move to the CPU on which the enqueue

 * function is invoked via mod_timer() or add_timer().  If the timer

 * should be placed on a particular CPU, then add_timer_on() has to be

 * used.

 */

#define TIMER_CPUMASK		0x0003FFFF

#define TIMER_MIGRATING		0x00040000

CRA Git | Maintained and supported by SUSTech CRA and CCSE