include/linux/timer.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_TIMER_H
   3 #define _LINUX_TIMER_H
   4
   5 #include <linux/list.h>
   6 #include <linux/ktime.h>
   7 #include <linux/stddef.h>
   8 #include <linux/debugobjects.h>
   9 #include <linux/stringify.h>
  10 #include <linux/timer_types.h>
  11
  12 #ifdef CONFIG_LOCKDEP
  13 /*
  14  * NB: because we have to copy the lockdep_map, setting the lockdep_map key
  15  * (second argument) here is required, otherwise it could be initialised to
  16  * the copy of the lockdep_map later! We use the pointer to and the string
  17  * "<file>:<line>" as the key resp. the name of the lockdep_map.
  18  */
  19 #define __TIMER_LOCKDEP_MAP_INITIALIZER(_kn)                            \
  20         .lockdep_map = STATIC_LOCKDEP_MAP_INIT(_kn, &_kn),
  21 #else
  22 #define __TIMER_LOCKDEP_MAP_INITIALIZER(_kn)
  23 #endif
  24
  25 /**
  26  * @TIMER_DEFERRABLE: A deferrable timer will work normally when the
  27  * system is busy, but will not cause a CPU to come out of idle just
  28  * to service it; instead, the timer will be serviced when the CPU
  29  * eventually wakes up with a subsequent non-deferrable timer.
  30  *
  31  * @TIMER_IRQSAFE: An irqsafe timer is executed with IRQ disabled and
  32  * it's safe to wait for the completion of the running instance from
  33  * IRQ handlers, for example, by calling del_timer_sync().
  34  *
  35  * Note: The irq disabled callback execution is a special case for
  36  * workqueue locking issues. It's not meant for executing random crap
  37  * with interrupts disabled. Abuse is monitored!
  38  *
  39  * @TIMER_PINNED: A pinned timer will not be affected by any timer
  40  * placement heuristics (like, NOHZ) and will always expire on the CPU
  41  * on which the timer was enqueued.
  42  *
  43  * Note: Because enqueuing of timers can migrate the timer from one
  44  * CPU to another, pinned timers are not guaranteed to stay on the
  45  * initialy selected CPU.  They move to the CPU on which the enqueue
  46  * function is invoked via mod_timer() or add_timer().  If the timer
  47  * should be placed on a particular CPU, then add_timer_on() has to be
  48  * used.
  49  */
  50 #define TIMER_CPUMASK           0x0003FFFF
  51 #define TIMER_MIGRATING         0x00040000
  52 #define TIMER_BASEMASK          (TIMER_CPUMASK | TIMER_MIGRATING)
  53 #define TIMER_DEFERRABLE        0x00080000
  54 #define TIMER_PINNED            0x00100000
  55 #define TIMER_IRQSAFE           0x00200000
  56 #define TIMER_INIT_FLAGS        (TIMER_DEFERRABLE | TIMER_PINNED | TIMER_IRQSAFE)
  57 #define TIMER_ARRAYSHIFT        22
  58 #define TIMER_ARRAYMASK         0xFFC00000
  59
  60 #define TIMER_TRACE_FLAGMASK    (TIMER_MIGRATING | TIMER_DEFERRABLE | TIMER_PINNED | TIMER_IRQSAFE)
  61
  62 #define __TIMER_INITIALIZER(_function, _flags) {                \
  63                 .entry = { .next = TIMER_ENTRY_STATIC },        \
  64                 .function = (_function),                        \
  65                 .flags = (_flags),                              \
  66                 __TIMER_LOCKDEP_MAP_INITIALIZER(FILE_LINE)      \
  67         }
  68
  69 #define DEFINE_TIMER(_name, _function)                          \
  70         struct timer_list _name =                               \
  71                 __TIMER_INITIALIZER(_function, 0)
  72
  73 /*
  74  * LOCKDEP and DEBUG timer interfaces.
  75  */
  76 void init_timer_key(struct timer_list *timer,
  77                     void (*func)(struct timer_list *), unsigned int flags,
  78                     const char *name, struct lock_class_key *key);
  79
  80 #ifdef CONFIG_DEBUG_OBJECTS_TIMERS
  81 extern void init_timer_on_stack_key(struct timer_list *timer,
  82                                     void (*func)(struct timer_list *),
  83                                     unsigned int flags, const char *name,
  84                                     struct lock_class_key *key);
  85 #else
  86 static inline void init_timer_on_stack_key(struct timer_list *timer,
  87                                            void (*func)(struct timer_list *),
  88                                            unsigned int flags,
  89                                            const char *name,
  90                                            struct lock_class_key *key)
  91 {
  92         init_timer_key(timer, func, flags, name, key);
  93 }
  94 #endif
  95
  96 #ifdef CONFIG_LOCKDEP
  97 #define __init_timer(_timer, _fn, _flags)                               \
  98         do {                                                            \
  99                 static struct lock_class_key __key;                     \
 100                 init_timer_key((_timer), (_fn), (_flags), #_timer, &__key);\
 101         } while (0)
 102
 103 #define __init_timer_on_stack(_timer, _fn, _flags)                      \
 104         do {                                                            \
 105                 static struct lock_class_key __key;                     \
 106                 init_timer_on_stack_key((_timer), (_fn), (_flags),      \
 107                                         #_timer, &__key);                \
 108         } while (0)
 109 #else
 110 #define __init_timer(_timer, _fn, _flags)                               \
 111         init_timer_key((_timer), (_fn), (_flags), NULL, NULL)
 112 #define __init_timer_on_stack(_timer, _fn, _flags)                      \
 113         init_timer_on_stack_key((_timer), (_fn), (_flags), NULL, NULL)
 114 #endif
 115
 116 /**
 117  * timer_setup - prepare a timer for first use
 118  * @timer: the timer in question
 119  * @callback: the function to call when timer expires
 120  * @flags: any TIMER_* flags
 121  *
 122  * Regular timer initialization should use either DEFINE_TIMER() above,
 123  * or timer_setup(). For timers on the stack, timer_setup_on_stack() must
 124  * be used and must be balanced with a call to destroy_timer_on_stack().
 125  */
 126 #define timer_setup(timer, callback, flags)                     \
 127         __init_timer((timer), (callback), (flags))
 128
 129 #define timer_setup_on_stack(timer, callback, flags)            \
 130         __init_timer_on_stack((timer), (callback), (flags))
 131
 132 #ifdef CONFIG_DEBUG_OBJECTS_TIMERS
 133 extern void destroy_timer_on_stack(struct timer_list *timer);
 134 #else
 135 static inline void destroy_timer_on_stack(struct timer_list *timer) { }
 136 #endif
 137
 138 #define from_timer(var, callback_timer, timer_fieldname) \
 139         container_of(callback_timer, typeof(*var), timer_fieldname)
 140
 141 /**
 142  * timer_pending - is a timer pending?
 143  * @timer: the timer in question
 144  *
 145  * timer_pending will tell whether a given timer is currently pending,
 146  * or not. Callers must ensure serialization wrt. other operations done
 147  * to this timer, eg. interrupt contexts, or other CPUs on SMP.
 148  *
 149  * return value: 1 if the timer is pending, 0 if not.
 150  */
 151 static inline int timer_pending(const struct timer_list * timer)
 152 {
 153         return !hlist_unhashed_lockless(&timer->entry);
 154 }
 155
 156 extern void add_timer_on(struct timer_list *timer, int cpu);
 157 extern int mod_timer(struct timer_list *timer, unsigned long expires);
 158 extern int mod_timer_pending(struct timer_list *timer, unsigned long expires);
 159 extern int timer_reduce(struct timer_list *timer, unsigned long expires);
 160
 161 /*
 162  * The jiffies value which is added to now, when there is no timer
 163  * in the timer wheel:
 164  */
 165 #define NEXT_TIMER_MAX_DELTA    ((1UL << 30) - 1)
 166
 167 extern void add_timer(struct timer_list *timer);
 168
 169 extern int try_to_del_timer_sync(struct timer_list *timer);
 170 extern int timer_delete_sync(struct timer_list *timer);
 171 extern int timer_delete(struct timer_list *timer);
 172 extern int timer_shutdown_sync(struct timer_list *timer);
 173 extern int timer_shutdown(struct timer_list *timer);
 174
 175 /**
 176  * del_timer_sync - Delete a pending timer and wait for a running callback
 177  * @timer:      The timer to be deleted
 178  *
 179  * See timer_delete_sync() for detailed explanation.
 180  *
 181  * Do not use in new code. Use timer_delete_sync() instead.
 182  */
 183 static inline int del_timer_sync(struct timer_list *timer)
 184 {
 185         return timer_delete_sync(timer);
 186 }
 187
 188 /**
 189  * del_timer - Delete a pending timer
 190  * @timer:      The timer to be deleted
 191  *
 192  * See timer_delete() for detailed explanation.
 193  *
 194  * Do not use in new code. Use timer_delete() instead.
 195  */
 196 static inline int del_timer(struct timer_list *timer)
 197 {
 198         return timer_delete(timer);
 199 }
 200
 201 extern void init_timers(void);
 202 struct hrtimer;
 203 extern enum hrtimer_restart it_real_fn(struct hrtimer *);
 204
 205 unsigned long __round_jiffies(unsigned long j, int cpu);
 206 unsigned long __round_jiffies_relative(unsigned long j, int cpu);
 207 unsigned long round_jiffies(unsigned long j);
 208 unsigned long round_jiffies_relative(unsigned long j);
 209
 210 unsigned long __round_jiffies_up(unsigned long j, int cpu);
 211 unsigned long __round_jiffies_up_relative(unsigned long j, int cpu);
 212 unsigned long round_jiffies_up(unsigned long j);
 213 unsigned long round_jiffies_up_relative(unsigned long j);
 214
 215 #ifdef CONFIG_HOTPLUG_CPU
 216 int timers_prepare_cpu(unsigned int cpu);
 217 int timers_dead_cpu(unsigned int cpu);
 218 #else
 219 #define timers_prepare_cpu      NULL
 220 #define timers_dead_cpu         NULL
 221 #endif
 222
 223 #endif