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 July 25, 2020
  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_FROMNMI
 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 .It Dv SWI_FROMNMI
 150 Specifies that
 151 .Fn swi_sched
 152 is called from NMI context and should be careful about used KPIs.
 153 On platforms allowing IPI sending from NMI context it immediately wakes
 154 .Va clk_intr_event
 155 via the IPI, otherwise it works just like SWI_DELAY.
 156 .El
 157 .Pp
 158 The
 159 .Va tty_intr_event
 160 and
 161 .Va clk_intr_event
 162 variables contain pointers to the software interrupt handlers for the tty and
 163 clock software interrupts, respectively.
 164 .Va tty_intr_event
 165 is used to hang tty software interrupt handlers off of the same thread.
 166 .Va clk_intr_event
 167 is used to hang delayed handlers off of the clock software interrupt thread so
 168 that the functionality of
 169 .Fn setdelayed
 170 can be obtained in conjunction with
 171 .Dv SWI_DELAY .
 172 The
 173 .Va vm_ih
 174 handler cookie is used to schedule software interrupt threads to run for the
 175 VM subsystem.
 176 .Sh RETURN VALUES
 177 The
 178 .Fn swi_add
 179 and
 180 .Fn swi_remove
 181 functions return zero on success and non-zero on failure.
 182 .Sh ERRORS
 183 The
 184 .Fn swi_add
 185 function will fail if:
 186 .Bl -tag -width Er
 187 .It Bq Er EAGAIN
 188 The system-imposed limit on the total
 189 number of processes under execution would be exceeded.
 190 The limit is given by the
 191 .Xr sysctl 3
 192 MIB variable
 193 .Dv KERN_MAXPROC .
 194 .It Bq Er EINVAL
 195 The
 196 .Fa flags
 197 argument specifies
 198 .Dv INTR_ENTROPY .
 199 .It Bq Er EINVAL
 200 The
 201 .Fa eventp
 202 argument points to a hardware interrupt thread.
 203 .It Bq Er EINVAL
 204 Either of the
 205 .Fa name
 206 or
 207 .Fa handler
 208 arguments are
 209 .Dv NULL .
 210 .It Bq Er EINVAL
 211 The
 212 .Dv INTR_EXCL
 213 flag is specified and the interrupt event pointed to by
 214 .Fa eventp
 215 already has at least one handler, or the interrupt event already has an
 216 exclusive handler.
 217 .El
 218 .Pp
 219 The
 220 .Fn swi_remove
 221 function will fail if:
 222 .Bl -tag -width Er
 223 .It Bq Er EINVAL
 224 A software interrupt handler pointed to by
 225 .Fa cookie
 226 is
 227 .Dv NULL .
 228 .El
 229 .Sh SEE ALSO
 230 .Xr ithread 9 ,
 231 .Xr taskqueue 9
 232 .Sh HISTORY
 233 The
 234 .Fn swi_add
 235 and
 236 .Fn swi_sched
 237 functions first appeared in
 238 .Fx 5.0 .
 239 They replaced the
 240 .Fn register_swi
 241 function which appeared in
 242 .Fx 3.0
 243 and the
 244 .Fn setsoft* ,
 245 and
 246 .Fn schedsoft*
 247 functions which date back to at least
 248 .Bx 4.4 .
 249 The
 250 .Fn swi_remove
 251 function first appeared in
 252 .Fx 6.1 .
 253 .Sh BUGS
 254 Most of the global variables described in this manual page should not be
 255 global, or at the very least should not be declared in
 256 .In sys/interrupt.h .