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