share/man/man9/swi.9

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