share/man/man9/softintr.9

   1 .\"     $NetBSD: softintr.9,v 1.19 2009/05/18 14:05:15 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2007, 2008 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Andrew Doran.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .\" Copyright (c) 2000 Christopher G. Demetriou.
  31 .\" All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer.
  38 .\" 2. Redistributions in binary form must reproduce the above copyright
  39 .\"    notice, this list of conditions and the following disclaimer in the
  40 .\"    documentation and/or other materials provided with the distribution.
  41 .\" 3. All advertising materials mentioning features or use of this software
  42 .\"    must display the following acknowledgement:
  43 .\"          This product includes software developed for the
  44 .\"          NetBSD Project.  See http://www.NetBSD.org/ for
  45 .\"          information about NetBSD.
  46 .\" 4. The name of the author may not be used to endorse or promote products
  47 .\"    derived from this software without specific prior written permission.
  48 .\"
  49 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  50 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  51 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  52 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  53 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  54 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  55 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  56 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  57 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  58 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  59 .\"
  60 .\" --(license Id: LICENSE.proto,v 1.1 2000/06/13 21:40:26 cgd Exp )--
  61 .\"
  62 .Dd August 3, 2009
  63 .Dt SOFTINT 9
  64 .Os
  65 .Sh NAME
  66 .Nm softint ,
  67 .Nm softint_establish ,
  68 .Nm softint_disestablish ,
  69 .Nm softint_schedule
  70 .Nd machine-independent software interrupt framework
  71 .Sh SYNOPSIS
  72 .In sys/intr.h
  73 .Ft void *
  74 .Fn softint_establish "u_int flags" "void (*func)(void *)" "void *arg"
  75 .Ft void
  76 .Fn softint_disestablish "void *cookie"
  77 .Ft void
  78 .Fn softint_schedule "void *cookie"
  79 .Sh DESCRIPTION
  80 The software interrupt framework is designed to provide
  81 a generic software interrupt mechanism which can be used any time a
  82 low-priority callback is needed.
  83 .Pp
  84 It allows dynamic registration of software interrupts for loadable
  85 drivers and protocol stacks, prioritization and fair queueing of software
  86 interrupts, and allows machine-dependent optimizations to reduce cost.
  87 .Pp
  88 Four priority levels are provided.
  89 In order of priority (lowest to highest) the levels are: clock, bio,
  90 net, serial.
  91 The names are symbolic and in isolation do not have any direct
  92 connection with a particular kind of device activity: they are
  93 only meant as a guide.
  94 .Pp
  95 The four priority levels map directly to scheduler priority
  96 levels, and where the architecture implements
  97 .Dq fast
  98 software interrupts, they also map onto interrupt priorities.
  99 The interrupt priorities are intended to be hidden from machine
 100 independent code, which should in general use thread-safe mechanisms
 101 to synchronize with software interrupts (for example: mutexes).
 102 .Pp
 103 Software interrupts run with limited machine context.
 104 In particular, they do not possess any address space context.
 105 They should not try to operate on user space addresses, or to use
 106 virtual memory facilities other than those noted as interrupt
 107 safe.
 108 Unlike hardware interrupts, software interrupts do have thread
 109 context.
 110 They may block on synchronization objects, sleep, and resume
 111 execution at a later time.
 112 .Pp
 113 Since software interrupts are a limited resource and run with
 114 higher priority than most other LWPs in the system, all
 115 block-and-resume activity by a software interrupt must be kept
 116 short to allow further processing at that level to continue.
 117 By extension, code running with process context must take care to
 118 ensure that any lock that may be taken from a software interrupt
 119 can not be held for more than a short period of time.
 120 .Pp
 121 The kernel does not allow software interrupts to use facilities
 122 or perform actions that are likely to block for a significant
 123 amount of time.
 124 This means that it's not valid for a software interrupt to
 125 sleep on condition variables or to wait for resources to
 126 become available (for example, memory).
 127 .Pp
 128 The following is a brief description of each function in the framework:
 129 .Bl -tag -width abcxdcc
 130 .It Fn softint_establish flags func arg
 131 .Pp
 132 Register a software interrupt.
 133 The
 134 .Fa flags
 135 value must contain one of the following constants, specifing
 136 the priority level for the soft interrupt:
 137 .Pp
 138 .Dv SOFTINT_CLOCK ,
 139 .Dv SOFTINT_BIO ,
 140 .Dv SOFTINT_NET ,
 141 .Dv SOFTINT_SERIAL
 142 .Pp
 143 If the constant
 144 .Dv SOFTINT_MPSAFE
 145 is not logically ORed into
 146 .Fa flags ,
 147 the global
 148 .Dv kernel_lock
 149 will automatically be acquired before the soft interrupt handler
 150 is called.
 151 .Pp
 152 The constant
 153 .Fa func
 154 specifies the function to call when the soft interrupt is
 155 executed.
 156 The argument
 157 .Fa arg
 158 will be passed to this function.
 159 .Pp
 160 .Fn softint_establish
 161 may block in order to allocate memory.
 162 If successful, it returns a
 163 .Pf non- Dv NULL
 164 opaque value to be used as an argument to
 165 .Fn softint_schedule
 166 and/or
 167 .Fn softint_disestablish .
 168 If for some reason it does not succeed, it returns
 169 .Dv NULL .
 170 .It Fn softint_disestablish cookie
 171 .Pp
 172 Deallocate a software interrupt previously allocated
 173 by a call to
 174 .Fn softint_establish .
 175 .\" XXX What happens to pending scheduled calls?
 176 .It Fn softint_schedule cookie
 177 .Pp
 178 Schedule a software interrupt previously allocated
 179 by a call to
 180 .Fn softint_establish
 181 to be executed as soon as that software interrupt is unblocked.
 182 .Fn softint_schedule
 183 can safely be called multiple times before the
 184 callback routine is invoked.
 185 .Pp
 186 Soft interrupt scheduling is CPU-local.
 187 A request to dispatch a soft interrupt will only be serviced on
 188 the same CPU where the request was made.
 189 The LWPs (light weight processes) dedicated to soft interrupt
 190 processing are bound to their home CPUs, so if a soft interrupt
 191 handler sleeps and later resumes, it will always resume on the
 192 same CPU.
 193 .Pp
 194 On a system with multiple processors, multiple instances of
 195 the same soft interrupt handler can be in flight simultaneously
 196 (at most one per-CPU).
 197 .El
 198 .Sh SEE ALSO
 199 .Xr callout 9 ,
 200 .Xr condvar 9 ,
 201 .Xr kthread 9 ,
 202 .Xr mutex 9 ,
 203 .Xr rwlock 9 ,
 204 .Xr spl 9 ,
 205 .Xr workqueue 9
 206 .Sh HISTORY
 207 The
 208 .Nx
 209 machine-independent software interrupt framework was designed in 1997
 210 and was implemented by one port in
 211 .Nx 1.3 .
 212 However, it did not gain wider implementation until
 213 .Nx 1.5 .
 214 Between
 215 .Nx 4.0
 216 and
 217 .Nx 5.0
 218 the framework was re-implemented in a machine-independant way to
 219 provide software interrupts with thread context.