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 always expire on the CPU on which the
  40  * timer was enqueued. When a particular CPU is required, add_timer_on()
  41  * has to be used. Enqueue via mod_timer() and add_timer() is always done
  42  * on the local CPU.
  43  */
  44 #define TIMER_CPUMASK           0x0003FFFF
  45 #define TIMER_MIGRATING         0x00040000
  46 #define TIMER_BASEMASK          (TIMER_CPUMASK | TIMER_MIGRATING)
  47 #define TIMER_DEFERRABLE        0x00080000
  48 #define TIMER_PINNED            0x00100000
  49 #define TIMER_IRQSAFE           0x00200000
  50 #define TIMER_INIT_FLAGS        (TIMER_DEFERRABLE | TIMER_PINNED | TIMER_IRQSAFE)
  51 #define TIMER_ARRAYSHIFT        22
  52 #define TIMER_ARRAYMASK         0xFFC00000
  53
  54 #define TIMER_TRACE_FLAGMASK    (TIMER_MIGRATING | TIMER_DEFERRABLE | TIMER_PINNED | TIMER_IRQSAFE)
  55
  56 #define __TIMER_INITIALIZER(_function, _flags) {                \
  57                 .entry = { .next = TIMER_ENTRY_STATIC },        \
  58                 .function = (_function),                        \
  59                 .flags = (_flags),                              \
  60                 __TIMER_LOCKDEP_MAP_INITIALIZER(FILE_LINE)      \
  61         }
  62
  63 #define DEFINE_TIMER(_name, _function)                          \
  64         struct timer_list _name =                               \
  65                 __TIMER_INITIALIZER(_function, 0)
  66
  67 /*
  68  * LOCKDEP and DEBUG timer interfaces.
  69  */
  70 void init_timer_key(struct timer_list *timer,
  71                     void (*func)(struct timer_list *), unsigned int flags,
  72                     const char *name, struct lock_class_key *key);
  73
  74 #ifdef CONFIG_DEBUG_OBJECTS_TIMERS
  75 extern void init_timer_on_stack_key(struct timer_list *timer,
  76                                     void (*func)(struct timer_list *),
  77                                     unsigned int flags, const char *name,
  78                                     struct lock_class_key *key);
  79 #else
  80 static inline void init_timer_on_stack_key(struct timer_list *timer,
  81                                            void (*func)(struct timer_list *),
  82                                            unsigned int flags,
  83                                            const char *name,
  84                                            struct lock_class_key *key)
  85 {
  86         init_timer_key(timer, func, flags, name, key);
  87 }
  88 #endif
  89
  90 #ifdef CONFIG_LOCKDEP
  91 #define __init_timer(_timer, _fn, _flags)                               \
  92         do {                                                            \
  93                 static struct lock_class_key __key;                     \
  94                 init_timer_key((_timer), (_fn), (_flags), #_timer, &__key);\
  95         } while (0)
  96
  97 #define __init_timer_on_stack(_timer, _fn, _flags)                      \
  98         do {                                                            \
  99                 static struct lock_class_key __key;                     \
 100                 init_timer_on_stack_key((_timer), (_fn), (_flags),      \
 101                                         #_timer, &__key);                \
 102         } while (0)
 103 #else
 104 #define __init_timer(_timer, _fn, _flags)                               \
 105         init_timer_key((_timer), (_fn), (_flags), NULL, NULL)
 106 #define __init_timer_on_stack(_timer, _fn, _flags)                      \
 107         init_timer_on_stack_key((_timer), (_fn), (_flags), NULL, NULL)
 108 #endif
 109
 110 /**
 111  * timer_setup - prepare a timer for first use
 112  * @timer: the timer in question
 113  * @callback: the function to call when timer expires
 114  * @flags: any TIMER_* flags
 115  *
 116  * Regular timer initialization should use either DEFINE_TIMER() above,
 117  * or timer_setup(). For timers on the stack, timer_setup_on_stack() must
 118  * be used and must be balanced with a call to destroy_timer_on_stack().
 119  */
 120 #define timer_setup(timer, callback, flags)                     \
 121         __init_timer((timer), (callback), (flags))
 122
 123 #define timer_setup_on_stack(timer, callback, flags)            \
 124         __init_timer_on_stack((timer), (callback), (flags))
 125
 126 #ifdef CONFIG_DEBUG_OBJECTS_TIMERS
 127 extern void destroy_timer_on_stack(struct timer_list *timer);
 128 #else
 129 static inline void destroy_timer_on_stack(struct timer_list *timer) { }
 130 #endif
 131
 132 #define from_timer(var, callback_timer, timer_fieldname) \
 133         container_of(callback_timer, typeof(*var), timer_fieldname)
 134
 135 /**
 136  * timer_pending - is a timer pending?
 137  * @timer: the timer in question
 138  *
 139  * timer_pending will tell whether a given timer is currently pending,
 140  * or not. Callers must ensure serialization wrt. other operations done
 141  * to this timer, eg. interrupt contexts, or other CPUs on SMP.
 142  *
 143  * Returns: 1 if the timer is pending, 0 if not.
 144  */
 145 static inline int timer_pending(const struct timer_list * timer)
 146 {
 147         return !hlist_unhashed_lockless(&timer->entry);
 148 }
 149
 150 extern void add_timer_on(struct timer_list *timer, int cpu);
 151 extern int mod_timer(struct timer_list *timer, unsigned long expires);
 152 extern int mod_timer_pending(struct timer_list *timer, unsigned long expires);
 153 extern int timer_reduce(struct timer_list *timer, unsigned long expires);
 154
 155 /*
 156  * The jiffies value which is added to now, when there is no timer
 157  * in the timer wheel:
 158  */
 159 #define NEXT_TIMER_MAX_DELTA    ((1UL << 30) - 1)
 160
 161 extern void add_timer(struct timer_list *timer);
 162 extern void add_timer_local(struct timer_list *timer);
 163 extern void add_timer_global(struct timer_list *timer);
 164
 165 extern int try_to_del_timer_sync(struct timer_list *timer);
 166 extern int timer_delete_sync(struct timer_list *timer);
 167 extern int timer_delete(struct timer_list *timer);
 168 extern int timer_shutdown_sync(struct timer_list *timer);
 169 extern int timer_shutdown(struct timer_list *timer);
 170
 171 /**
 172  * del_timer_sync - Delete a pending timer and wait for a running callback
 173  * @timer:      The timer to be deleted
 174  *
 175  * See timer_delete_sync() for detailed explanation.
 176  *
 177  * Do not use in new code. Use timer_delete_sync() instead.
 178  *
 179  * Returns:
 180  * * %0 - The timer was not pending
 181  * * %1 - The timer was pending and deactivated
 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  * Returns:
 197  * * %0 - The timer was not pending
 198  * * %1 - The timer was pending and deactivated
 199  */
 200 static inline int del_timer(struct timer_list *timer)
 201 {
 202         return timer_delete(timer);
 203 }
 204
 205 extern void init_timers(void);
 206 struct hrtimer;
 207 extern enum hrtimer_restart it_real_fn(struct hrtimer *);
 208
 209 unsigned long __round_jiffies(unsigned long j, int cpu);
 210 unsigned long __round_jiffies_relative(unsigned long j, int cpu);
 211 unsigned long round_jiffies(unsigned long j);
 212 unsigned long round_jiffies_relative(unsigned long j);
 213
 214 unsigned long __round_jiffies_up(unsigned long j, int cpu);
 215 unsigned long __round_jiffies_up_relative(unsigned long j, int cpu);
 216 unsigned long round_jiffies_up(unsigned long j);
 217 unsigned long round_jiffies_up_relative(unsigned long j);
 218
 219 #ifdef CONFIG_HOTPLUG_CPU
 220 int timers_prepare_cpu(unsigned int cpu);
 221 int timers_dead_cpu(unsigned int cpu);
 222 #else
 223 #define timers_prepare_cpu      NULL
 224 #define timers_dead_cpu         NULL
 225 #endif
 226
 227 #endif