sys/sys/callout.h

   1 /*
   2  * Copyright (c) 2014 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. All advertising materials mentioning features or use of this software
  53  *    must display the following acknowledgement:
  54  *      This product includes software developed by the University of
  55  *      California, Berkeley and its contributors.
  56  * 4. Neither the name of the University nor the names of its contributors
  57  *    may be used to endorse or promote products derived from this software
  58  *    without specific prior written permission.
  59  *
  60  * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  61  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  62  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  63  * ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  64  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  65  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  66  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  67  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  68  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  69  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  70  * SUCH DAMAGE.
  71  */
  72
  73 #ifndef _SYS_CALLOUT_H_
  74 #define _SYS_CALLOUT_H_
  75
  76 #ifndef _SYS_QUEUE_H_
  77 #include <sys/queue.h>
  78 #endif
  79 #ifndef _SYS_LOCK_H_
  80 #include <sys/lock.h>
  81 #endif
  82 #ifndef _CPU_ATOMIC_H_
  83 #include <machine/atomic.h>
  84 #endif
  85
  86 SLIST_HEAD(callout_list, callout);
  87 TAILQ_HEAD(callout_tailq, callout);
  88
  89 /*
  90  * Callwheel linkages are only adjusted on the target cpu.  All other
  91  * actions are handled with atomic ops on any cpu.  callout_reset() and
  92  * callout_stop() are always synchronous and will interlock against a
  93  * running callout.  The caller might block, and a deadlock is possible
  94  * if the caller does not use callout_init_lk() or is not careful with
  95  * locks acquired in the callout function.
  96  *
  97  * Programers should note that our lockmgr locks have a cancelation feature
  98  * which can be used to avoid deadlocks.  callout_init_lk() also uses this
  99  * feature.
 100  *
 101  * callout_deactivate() is asynchronous and will not interlock against
 102  * callout which is already running.
 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_unused02;
 115         struct lock *c_lk;              /* auto-lock */
 116 };
 117
 118 #define CALLOUT_ACTIVE          0x80000000 /* quick [de]activation flag */
 119 #define CALLOUT_PENDING         0x40000000 /* callout is on callwheel */
 120 #define CALLOUT_MPSAFE          0x20000000 /* callout does not need the BGL */
 121 #define CALLOUT_DID_INIT        0x10000000 /* safety check */
 122 #define CALLOUT_AUTOLOCK        0x08000000 /* auto locking / cancel feature */
 123 #define CALLOUT_WAITING         0x04000000 /* interlocked waiter */
 124 #define CALLOUT_EXECUTED        0x02000000 /* (generates stop status) */
 125 #define CALLOUT_ARMED           0x01000000 /* callout is assigned to cpu */
 126 #define CALLOUT_IPI_MASK        0x00000FFF /* ipi in-flight count mask */
 127 #define CALLOUT_CPU_MASK        0x00FFF000 /* ipi in-flight count mask */
 128
 129 #define CALLOUT_FLAGS_TO_CPU(flags)     (((flags) & CALLOUT_CPU_MASK) >> 12)
 130 #define CALLOUT_CPU_TO_FLAGS(cpuid)     ((cpuid) << 12)
 131
 132 /*
 133  * WARNING! The caller is responsible for stabilizing the callout state,
 134  *          our suggestion is to either manage the callout on the same cpu
 135  *          or to use the callout_init_lk() feature and hold the lock while
 136  *          making callout_*() calls.  The lock will be held automatically
 137  *          by the callout wheel for any call-back and the callout wheel
 138  *          will handle any callout_stop() deadlocks properly.
 139  *
 140  * active  -    Indicates that the callout is armed.  The callout can be in
 141  *              any state other than a stopped state.  That is, the callout
 142  *              reset could still be inflight to the target cpu and not yet
 143  *              pending on the target cpu's callwheel, could be pending on
 144  *              the callwheel, may have already executed (but not have been
 145  *              stopped), or might be executing concurrently.
 146  *
 147  * deactivate - Disarm the callout, preventing it from being executed if it
 148  *              is queued or the queueing operation is in-flight.  Has no
 149  *              effect if the callout has already been dispatched.  Does not
 150  *              dequeue the callout.  Does not affect the status returned
 151  *              by callout_stop().
 152  *
 153  *              Not serialized, caller must be careful when racing a new
 154  *              callout_reset() that might be issued by the callback, which
 155  *              will re-arm the callout.
 156  *
 157  * pending -    Only useful for same-cpu callouts, indicates that the callout
 158  *              is pending on the callwheel or that a callout_reset() ipi
 159  *              is in-flight.
 160  */
 161 #define callout_active(c)       ((c)->c_flags & CALLOUT_ACTIVE)
 162
 163 #define callout_deactivate(c)   atomic_clear_int(&(c)->c_flags, CALLOUT_ACTIVE)
 164
 165 #define callout_pending(c)      ((c)->c_flags & (CALLOUT_PENDING |      \
 166                                                  CALLOUT_IPI_MASK))
 167
 168 #ifdef _KERNEL
 169 extern int      ncallout;
 170
 171 struct globaldata;
 172
 173 void    hardclock_softtick(struct globaldata *);
 174 void    callout_init (struct callout *);
 175 void    callout_init_mp (struct callout *);
 176 void    callout_init_lk (struct callout *, struct lock *);
 177 void    callout_reset (struct callout *, int, void (*)(void *), void *);
 178 int     callout_stop (struct callout *);
 179 void    callout_stop_async (struct callout *);
 180 int     callout_stop_sync (struct callout *);
 181 void    callout_terminate (struct callout *);
 182 void    callout_reset_bycpu (struct callout *, int, void (*)(void *), void *,
 183             int);
 184
 185 #define callout_drain(x) callout_stop_sync(x)
 186
 187 #endif
 188
 189 #endif /* _SYS_CALLOUT_H_ */