ebd904615dd78a0a98f9b6944b52ce07ced794eb
[dragonfly.git] / sys / sys / callout.h
1 /*
2  * Copyright (c) 2014,2018 The DragonFly Project.  All rights reserved.
3  *
4  * This code is derived from software contributed to The DragonFly Project
5  * by Matthew Dillon <dillon@backplane.com>
6  *
7  * Redistribution and use in source and binary forms, with or without
8  * modification, are permitted provided that the following conditions
9  * are met:
10  *
11  * 1. Redistributions of source code must retain the above copyright
12  *    notice, this list of conditions and the following disclaimer.
13  * 2. Redistributions in binary form must reproduce the above copyright
14  *    notice, this list of conditions and the following disclaimer in
15  *    the documentation and/or other materials provided with the
16  *    distribution.
17  * 3. Neither the name of The DragonFly Project nor the names of its
18  *    contributors may be used to endorse or promote products derived
19  *    from this software without specific, prior written permission.
20  *
21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
24  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
25  * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
26  * INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
27  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
28  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
29  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
30  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
31  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32  * SUCH DAMAGE.
33  */
34 /*
35  * Copyright (c) 1990, 1993
36  *      The Regents of the University of California.  All rights reserved.
37  * (c) UNIX System Laboratories, Inc.
38  *
39  * All or some portions of this file are derived from material licensed
40  * to the University of California by American Telephone and Telegraph
41  * Co. or Unix System Laboratories, Inc. and are reproduced herein with
42  * the permission of UNIX System Laboratories, Inc.
43  *
44  * Redistribution and use in source and binary forms, with or without
45  * modification, are permitted provided that the following conditions
46  * are met:
47  * 1. Redistributions of source code must retain the above copyright
48  *    notice, this list of conditions and the following disclaimer.
49  * 2. Redistributions in binary form must reproduce the above copyright
50  *    notice, this list of conditions and the following disclaimer in the
51  *    documentation and/or other materials provided with the distribution.
52  * 3. Neither the name of the University nor the names of its contributors
53  *    may be used to endorse or promote products derived from this software
54  *    without specific prior written permission.
55  *
56  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
57  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
59  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
60  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
61  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
62  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
63  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
64  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
65  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
66  * SUCH DAMAGE.
67  */
68
69 #ifndef _SYS_CALLOUT_H_
70 #define _SYS_CALLOUT_H_
71
72 #ifndef _SYS_QUEUE_H_
73 #include <sys/queue.h>
74 #endif
75 #ifndef _SYS_LOCK_H_
76 #include <sys/lock.h>
77 #endif
78 #ifndef _CPU_ATOMIC_H_
79 #include <machine/atomic.h>
80 #endif
81
82 SLIST_HEAD(callout_list, callout);
83 TAILQ_HEAD(callout_tailq, callout);
84
85 /*
86  * Callwheel linkages are only adjusted on the target cpu.  The target
87  * cpu can only be [re]assigned when the IPI_MASK and PENDING bits are
88  * clear.
89  *
90  * callout_reset() and callout_stop() are always synchronous and will
91  * interlock against a running callout as well as reassign the callout
92  * to the current cpu.  The caller might block, and a deadlock is possible
93  * if the caller does not use callout_init_lk() or is not careful with
94  * locks acquired in the callout function.
95  *
96  * Programers should note that our lockmgr locks have a cancelation feature
97  * which can be used to avoid deadlocks.  callout_init_lk() also uses this
98  * feature.
99  *
100  * callout_deactivate() is asynchronous and will not interlock against
101  * anything.  Deactivation does not dequeue a callout, it simply prevents
102  * its function from being executed.
103  */
104 struct callout {
105         union {
106                 SLIST_ENTRY(callout) sle;
107                 TAILQ_ENTRY(callout) tqe;
108         } c_links;
109         int     c_time;                 /* match tick on event */
110         int     c_load;                 /* load value for reset ipi */
111         void    *c_arg;                 /* function argument */
112         void    (*c_func) (void *);     /* function to call */
113         int     c_flags;                /* state of this entry */
114         int     c_lineno;               /* debugging */
115         struct lock *c_lk;              /* auto-lock */
116         const char *c_ident;            /* debugging */
117 };
118
119 /*
120  * ACTIVE       - If cleared this the callout is prevented from issuing its
121  *                callback.  The callout remains on its timer queue.
122  *
123  * PENDING      - Indicates the callout is on a particular cpu's timer queue.
124  *                Also locks the cpu owning the callout.
125  *
126  * MPSAFE       - Indicates the callout does not need the MP lock (most
127  *                callouts are flagged this way).
128  *
129  * DID_INIT     - Safety
130  *
131  * EXECUTED     - Set prior to function dispatch, cleared by callout_reset(),
132  *                cleared and (prior value) returned by callout_stop_sync().
133  *
134  * WAITING      - Used for tsleep/wakeup blocking, primarily for
135  *                callout_stop().
136  *
137  * IPI_MASK     - Counts pending IPIs.  Also locks the cpu owning the callout.
138  *
139  * CPU_MASK     - Currently assigned cpu.  Only valid when at least one bit
140  *                in ARMED_MASK is set.
141  *
142  */
143 #define CALLOUT_ACTIVE          0x80000000 /* quick [de]activation flag */
144 #define CALLOUT_PENDING         0x40000000 /* callout is on callwheel */
145 #define CALLOUT_MPSAFE          0x20000000 /* callout does not need the BGL */
146 #define CALLOUT_DID_INIT        0x10000000 /* safety check */
147 #define CALLOUT_AUTOLOCK        0x08000000 /* auto locking / cancel feature */
148 #define CALLOUT_WAITING         0x04000000 /* interlocked waiter */
149 #define CALLOUT_EXECUTED        0x02000000 /* (generates stop status) */
150 #define CALLOUT_UNUSED01        0x01000000
151 #define CALLOUT_IPI_MASK        0x00000FFF /* count operations in prog */
152 #define CALLOUT_CPU_MASK        0x00FFF000 /* cpu assignment */
153
154 #define CALLOUT_ARMED_MASK      (CALLOUT_PENDING | CALLOUT_IPI_MASK)
155
156 #define CALLOUT_FLAGS_TO_CPU(flags)     (((flags) & CALLOUT_CPU_MASK) >> 12)
157 #define CALLOUT_CPU_TO_FLAGS(cpuid)     ((cpuid) << 12)
158
159 /*
160  * WARNING! The caller is responsible for stabilizing the callout state,
161  *          our suggestion is to either manage the callout on the same cpu
162  *          or to use the callout_init_lk() feature and hold the lock while
163  *          making callout_*() calls.  The lock will be held automatically
164  *          by the callout wheel for any call-back and the callout wheel
165  *          will handle any callout_stop() deadlocks properly.
166  *
167  * active  -    Returns activation status.  This bit is set by callout_reset*()
168  *              and will only be cleared by an explicit callout_deactivate()
169  *              or callout_stop().  A function dispatch does not clear this
170  *              bit.  In addition, a callout_reset() to another cpu is
171  *              asynchronous and may not immediately re-set this bit.
172  *
173  * deactivate - Disarm the callout, preventing it from being executed if it
174  *              is queued or the queueing operation is in-flight.  Has no
175  *              effect if the callout has already been dispatched.  Does not
176  *              dequeue the callout.  Does not affect the status returned
177  *              by callout_stop().
178  *
179  *              Not serialized, caller must be careful when racing a new
180  *              callout_reset() that might be issued by the callback, which
181  *              will re-arm the callout.
182  *
183  *              callout_reset() must be called to reactivate the callout.
184  *
185  * pending -    Only useful for same-cpu callouts, indicates that the callout
186  *              is pending on the callwheel or that a callout_reset() ipi
187  *              is (probably) in-flight.  Can also false-positive on
188  *              callout_stop() IPIs.
189  */
190 #define callout_active(c)       ((c)->c_flags & CALLOUT_ACTIVE)
191
192 #define callout_deactivate(c)   atomic_clear_int(&(c)->c_flags, CALLOUT_ACTIVE)
193
194 #define callout_pending(c)      ((c)->c_flags & CALLOUT_ARMED_MASK)
195
196 #ifdef _KERNEL
197 extern int      ncallout;
198
199 struct globaldata;
200
201 void    hardclock_softtick(struct globaldata *);
202 void    callout_init (struct callout *);
203 void    callout_init_mp (struct callout *);
204 void    callout_init_lk (struct callout *, struct lock *);
205 void    callout_initd (struct callout *, const char *, int);
206 void    callout_initd_mp (struct callout *, const char *, int);
207 void    callout_initd_lk (struct callout *, struct lock *, const char *, int);
208 void    callout_reset (struct callout *, int, void (*)(void *), void *);
209 int     callout_stop (struct callout *);
210 void    callout_stop_async (struct callout *);
211 int     callout_stop_sync (struct callout *);
212 void    callout_terminate (struct callout *);
213 void    callout_reset_bycpu (struct callout *, int, void (*)(void *), void *,
214             int);
215
216 #define callout_drain(x) callout_stop_sync(x)
217
218 #define CALLOUT_DEBUG
219 #ifdef CALLOUT_DEBUG
220 #define callout_init(co)        callout_initd(co, __FILE__, __LINE__)
221 #define callout_init_mp(co)     callout_initd_mp(co, __FILE__, __LINE__)
222 #define callout_init_lk(co, lk) callout_initd_lk(co, lk, __FILE__, __LINE__)
223 #endif
224
225 #endif
226
227 #endif /* _SYS_CALLOUT_H_ */