share/man/man9/swi.9

   1 .\" Copyright (c) 2000-2001 John H. Baldwin <jhb@FreeBSD.org>
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .Dd April 19, 2012
  27 .Dt SWI 9
  28 .Os
  29 .Sh NAME
  30 .Nm swi_add ,
  31 .Nm swi_remove ,
  32 .Nm swi_sched
  33 .Nd register and schedule software interrupt handlers
  34 .Sh SYNOPSIS
  35 .In sys/param.h
  36 .In sys/bus.h
  37 .In sys/interrupt.h
  38 .Vt "extern struct intr_event *tty_intr_event" ;
  39 .Vt "extern struct intr_event *clk_intr_event" ;
  40 .Vt "extern void *vm_ih" ;
  41 .Ft int
  42 .Fo swi_add
  43 .Fa "struct intr_event **eventp"
  44 .Fa "const char *name"
  45 .Fa "driver_intr_t handler"
  46 .Fa "void *arg"
  47 .Fa "int pri"
  48 .Fa "enum intr_type flags"
  49 .Fa "void **cookiep"
  50 .Fc
  51 .Ft int
  52 .Fn swi_remove "void *cookie"
  53 .Ft void
  54 .Fn swi_sched "void *cookie" "int flags"
  55 .Sh DESCRIPTION
  56 These functions are used to register and schedule software interrupt handlers.
  57 Software interrupt handlers are attached to a software interrupt thread, just
  58 as hardware interrupt handlers are attached to a hardware interrupt thread.
  59 Multiple handlers can be attached to the same thread.
  60 Software interrupt handlers can be used to queue up less critical processing
  61 inside of hardware interrupt handlers so that the work can be done at a later
  62 time.
  63 Software interrupt threads are different from other kernel threads in that they
  64 are treated as an interrupt thread.
  65 This means that time spent executing these threads is counted as interrupt
  66 time, and that they can be run via a lightweight context switch.
  67 .Pp
  68 The
  69 .Fn swi_add
  70 function is used to add a new software interrupt handler to a specified
  71 interrupt event.
  72 The
  73 .Fa eventp
  74 argument is an optional pointer to a
  75 .Vt struct intr_event
  76 pointer.
  77 If this argument points to an existing event that holds a list of
  78 interrupt handlers, then this handler will be attached to that event.
  79 Otherwise a new event will be created, and if
  80 .Fa eventp
  81 is not
  82 .Dv NULL ,
  83 then the pointer at that address to will be modified to point to the
  84 newly created event.
  85 The
  86 .Fa name
  87 argument is used to associate a name with a specific handler.
  88 This name is appended to the name of the software interrupt thread that this
  89 handler is attached to.
  90 The
  91 .Fa handler
  92 argument is the function that will be executed when the handler is scheduled
  93 to run.
  94 The
  95 .Fa arg
  96 parameter will be passed in as the only parameter to
  97 .Fa handler
  98 when the function is executed.
  99 The
 100 .Fa pri
 101 value specifies the priority of this interrupt handler relative to other
 102 software interrupt handlers.
 103 If an interrupt event is created, then this value is used as the vector,
 104 and the
 105 .Fa flags
 106 argument is used to specify the attributes of a handler such as
 107 .Dv INTR_MPSAFE .
 108 The
 109 .Fa cookiep
 110 argument points to a
 111 .Vt void *
 112 cookie.
 113 This cookie will be set to a value that uniquely identifies this handler,
 114 and is used to schedule the handler for execution later on.
 115 .Pp
 116 The
 117 .Fn swi_remove
 118 function is used to teardown an interrupt handler pointed to by the
 119 .Fa cookie
 120 argument.
 121 It detaches the interrupt handler from the associated interrupt event
 122 and frees its memory.
 123 .Pp
 124 The
 125 .Fn swi_sched
 126 function is used to schedule an interrupt handler and its associated thread to
 127 run.
 128 The
 129 .Fa cookie
 130 argument specifies which software interrupt handler should be scheduled to run.
 131 The
 132 .Fa flags
 133 argument specifies how and when the handler should be run and is a mask of one
 134 or more of the following flags:
 135 .Bl -tag -width SWI_DELAY
 136 .It Dv SWI_DELAY
 137 Specifies that the kernel should mark the specified handler as needing to run,
 138 but the kernel should not schedule the software interrupt thread to run.
 139 Instead,
 140 .Fa handler
 141 will be executed the next time that the software interrupt thread runs after
 142 being scheduled by another event.
 143 Attaching a handler to the clock software interrupt thread and using this flag
 144 when scheduling a software interrupt handler can be used to implement the
 145 functionality performed by
 146 .Fn setdelayed
 147 in earlier versions of
 148 .Fx .
 149 .El
 150 .Pp
 151 The
 152 .Va tty_intr_event
 153 and
 154 .Va clk_intr_event
 155 variables contain pointers to the software interrupt handlers for the tty and
 156 clock software interrupts, respectively.
 157 .Va tty_intr_event
 158 is used to hang tty software interrupt handlers off of the same thread.
 159 .Va clk_intr_event
 160 is used to hang delayed handlers off of the clock software interrupt thread so
 161 that the functionality of
 162 .Fn setdelayed
 163 can be obtained in conjunction with
 164 .Dv SWI_DELAY .
 165 The
 166 .Va vm_ih
 167 handler cookie is used to schedule software interrupt threads to run for the
 168 VM subsystem.
 169 .Sh RETURN VALUES
 170 The
 171 .Fn swi_add
 172 and
 173 .Fn swi_remove
 174 functions return zero on success and non-zero on failure.
 175 .Sh ERRORS
 176 The
 177 .Fn swi_add
 178 function will fail if:
 179 .Bl -tag -width Er
 180 .It Bq Er EAGAIN
 181 The system-imposed limit on the total
 182 number of processes under execution would be exceeded.
 183 The limit is given by the
 184 .Xr sysctl 3
 185 MIB variable
 186 .Dv KERN_MAXPROC .
 187 .It Bq Er EINVAL
 188 The
 189 .Fa flags
 190 argument specifies
 191 .Dv INTR_ENTROPY .
 192 .It Bq Er EINVAL
 193 The
 194 .Fa eventp
 195 argument points to a hardware interrupt thread.
 196 .It Bq Er EINVAL
 197 Either of the
 198 .Fa name
 199 or
 200 .Fa handler
 201 arguments are
 202 .Dv NULL .
 203 .It Bq Er EINVAL
 204 The
 205 .Dv INTR_EXCL
 206 flag is specified and the interrupt event pointed to by
 207 .Fa eventp
 208 already has at least one handler, or the interrupt event already has an
 209 exclusive handler.
 210 .El
 211 .Pp
 212 The
 213 .Fn swi_remove
 214 function will fail if:
 215 .Bl -tag -width Er
 216 .It Bq Er EINVAL
 217 A software interrupt handler pointed to by
 218 .Fa cookie
 219 is
 220 .Dv NULL .
 221 .El
 222 .Sh SEE ALSO
 223 .Xr ithread 9 ,
 224 .Xr taskqueue 9
 225 .Sh HISTORY
 226 The
 227 .Fn swi_add
 228 and
 229 .Fn swi_sched
 230 functions first appeared in
 231 .Fx 5.0 .
 232 They replaced the
 233 .Fn register_swi
 234 function which appeared in
 235 .Fx 3.0
 236 and the
 237 .Fn setsoft* ,
 238 and
 239 .Fn schedsoft*
 240 functions which date back to at least
 241 .Bx 4.4 .
 242 The
 243 .Fn swi_remove
 244 function first appeared in
 245 .Fx 6.1 .
 246 .Sh BUGS
 247 Most of the global variables described in this manual page should not be
 248 global, or at the very least should not be declared in
 249 .In sys/interrupt.h .