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 October 30, 2000
  28 .Dt SWI 9
  29 .Os
  30 .Sh NAME
  31 .Nm swi_add ,
  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 ithd *tty_ithd" ;
  39 .Vt "extern struct ithd *clk_ithd" ;
  40 .Vt "extern void *net_ih" ;
  41 .Vt "extern void *softclock_ih" ;
  42 .Vt "extern void *vm_ih" ;
  43 .Ft int
  44 .Fo swi_add
  45 .Fa "struct ithd **ithdp"
  46 .Fa "const char *name"
  47 .Fa "driver_intr_t handler"
  48 .Fa "void *arg"
  49 .Fa "int pri"
  50 .Fa "enum intr_type flags"
  51 .Fa "void **cookiep"
  52 .Fc
  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 register a new software interrupt handler.
  71 The
  72 .Fa ithdp
  73 argument is an optional pointer to a
  74 .Vt struct ithd
  75 pointer.
  76 If this argument points to an existing software interrupt thread, then this
  77 handler will be attached to that thread.
  78 Otherwise a new thread will be created, and if
  79 .Fa ithdp
  80 is not
  81 .Dv NULL ,
  82 then the pointer at that address to will be modified to point to the
  83 newly created thread.
  84 The
  85 .Fa name
  86 argument is used to associate a name with a specific handler.
  87 This name is appended to the name of the software interrupt thread that this
  88 handler is attached to.
  89 The
  90 .Fa handler
  91 argument is the function that will be executed when the handler is scheduled
  92 to run.
  93 The
  94 .Fa arg
  95 parameter will be passed in as the only parameter to
  96 .Fa handler
  97 when the function is executed.
  98 The
  99 .Fa pri
 100 value specifies the priority of this interrupt handler relative to other
 101 software interrupt handlers.
 102 If an interrupt thread is created, then this value is used as the vector,
 103 and the
 104 .Fa flags
 105 argument is used to specify the attributes of a handler such as
 106 .Dv INTR_MPSAFE .
 107 The
 108 .Fa cookiep
 109 argument points to a
 110 .Vt void *
 111 cookie.
 112 This cookie will be set to a value that uniquely identifies this handler,
 113 and is used to schedule the handler for execution later on.
 114 .Pp
 115 The
 116 .Fn swi_sched
 117 function is used to schedule an interrupt handler and its associated thread to
 118 run.
 119 The
 120 .Fa cookie
 121 argument specifies which software interrupt handler should be scheduled to run.
 122 The
 123 .Fa flags
 124 argument specifies how and when the handler should be run and is a mask of one
 125 or more of the following flags:
 126 .Bl -tag -width SWI_DELAY
 127 .It Dv SWI_DELAY
 128 Specifies that the kernel should mark the specified handler as needing to run,
 129 but the kernel should not schedule the software interrupt thread to run.
 130 Instead,
 131 .Fa handler
 132 will be executed the next time that the software interrupt thread runs after
 133 being scheduled by another event.
 134 Attaching a handler to the clock software interrupt thread and using this flag
 135 when scheduling a software interrupt handler can be used to implement the
 136 functionality performed by
 137 .Fn setdelayed
 138 in earlier versions of
 139 .Fx .
 140 .El
 141 .Pp
 142 The
 143 .Va tty_ithd
 144 and
 145 .Va clk_ithd
 146 variables contain pointers to the software interrupt threads for the tty and
 147 clock software interrupts, respectively.
 148 .Va tty_ithd
 149 is used to hang tty software interrupt handlers off of the same thread.
 150 .Va clk_ithd
 151 is used to hang delayed handlers off of the clock software interrupt thread so
 152 that the functionality of
 153 .Fn setdelayed
 154 can be obtained in conjunction with
 155 .Dv SWI_DELAY .
 156 The
 157 .Va net_ih ,
 158 .Va softclock_ih ,
 159 and
 160 .Va vm_ih
 161 handler cookies are used to schedule software interrupt threads to run for the
 162 networking stack, clock interrupt, and VM subsystem respectively.
 163 .Sh RETURN VALUES
 164 The
 165 .Fn swi_add
 166 function returns zero on success and non-zero on failure.
 167 .Sh ERRORS
 168 The
 169 .Fn swi_add
 170 function will fail if:
 171 .Bl -tag -width Er
 172 .It Bq Er EAGAIN
 173 The system-imposed limit on the total
 174 number of processes under execution would be exceeded.
 175 The limit is given by the
 176 .Xr sysctl 3
 177 MIB variable
 178 .Dv KERN_MAXPROC .
 179 .It Bq Er EINVAL
 180 The
 181 .Fa flags
 182 argument specifies either
 183 .Dv INTR_ENTROPY
 184 or
 185 .Dv INTR_FAST .
 186 .It Bq Er EINVAL
 187 The
 188 .Fa ithdp
 189 argument points to a hardware interrupt thread.
 190 .It Bq Er EINVAL
 191 Either of the
 192 .Fa name
 193 or
 194 .Fa handler
 195 arguments are
 196 .Dv NULL .
 197 .It Bq Er EINVAL
 198 The
 199 .Dv INTR_EXCL
 200 flag is specified and the interrupt thread pointed to by
 201 .Fa ithdp
 202 already has at least one handler, or the interrupt thread already has an
 203 exclusive handler.
 204 .El
 205 .Sh SEE ALSO
 206 .Xr ithread 9 ,
 207 .Xr taskqueue 9
 208 .Sh HISTORY
 209 The
 210 .Fn swi_add
 211 and
 212 .Fn swi_sched
 213 functions first appeared in
 214 .Fx 5.0 .
 215 They replaced the
 216 .Fn register_swi
 217 function which appeared in
 218 .Fx 3.0
 219 and the
 220 .Fn setsoft* ,
 221 and
 222 .Fn schedsoft*
 223 functions which date back to at least
 224 .Bx 4.4 .
 225 .Sh BUGS
 226 Most of the global variables described in this manual page should not be
 227 global, or at the very least should not be declared in
 228 .In sys/interrupt.h .