share/man/man9/ithread.9

   1 .\" Copyright (c) 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 August 25, 2006
  27 .Dt ITHREAD 9
  28 .Os
  29 .Sh NAME
  30 .Nm ithread_add_handler ,
  31 .Nm ithread_create ,
  32 .Nm ithread_destroy ,
  33 .Nm ithread_priority ,
  34 .Nm ithread_remove_handler ,
  35 .Nm ithread_schedule
  36 .Nd kernel interrupt threads
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/bus.h
  40 .In sys/interrupt.h
  41 .Ft int
  42 .Fo ithread_add_handler
  43 .Fa "struct ithd *ithread"
  44 .Fa "const char *name"
  45 .Fa "driver_intr_t handler"
  46 .Fa "void *arg"
  47 .Fa "u_char pri"
  48 .Fa "enum intr_type flags"
  49 .Fa "void **cookiep"
  50 .Fc
  51 .Ft int
  52 .Fo ithread_create
  53 .Fa "struct ithd **ithread"
  54 .Fa "int vector"
  55 .Fa "int flags"
  56 .Fa "void (*disable)(int)"
  57 .Fa "void (*enable)(int)"
  58 .Fa "const char *fmt"
  59 .Fa "..."
  60 .Fc
  61 .Ft int
  62 .Fn ithread_destroy "struct ithd *ithread"
  63 .Ft u_char
  64 .Fn ithread_priority "enum intr_type flags"
  65 .Ft int
  66 .Fn ithread_remove_handler "void *cookie"
  67 .Ft int
  68 .Fn ithread_schedule "struct ithd *ithread" "int do_switch"
  69 .Sh DESCRIPTION
  70 Interrupt threads are kernel threads that run a list of handlers when
  71 triggered by either a hardware or software interrupt.
  72 Each interrupt handler has a name, handler function, handler argument,
  73 priority, and various flags.
  74 Each interrupt thread maintains a list of handlers sorted by priority.
  75 This results in higher priority handlers being executed prior to lower
  76 priority handlers.
  77 Each thread assumes the priority of its highest priority handler for its
  78 process priority, or
  79 .Dv PRIO_MAX
  80 if it has no handlers.
  81 Interrupt threads are also associated with a single interrupt source,
  82 represented as a vector number.
  83 .Pp
  84 The
  85 .Fn ithread_create
  86 function creates a new interrupt thread.
  87 The
  88 .Fa ithread
  89 argument points to an
  90 .Vt struct ithd
  91 pointer that will point to the newly created thread upon success.
  92 The
  93 .Fa vector
  94 argument specifies the interrupt source to associate this thread with.
  95 The
  96 .Fa flags
  97 argument is a mask of properties of this thread.
  98 The only valid flag currently for
  99 .Fn ithread_create
 100 is
 101 .Dv IT_SOFT
 102 to specify that this interrupt thread is a software interrupt.
 103 The
 104 .Fa enable
 105 and
 106 .Fa disable
 107 arguments specify optional functions used to enable and disable this
 108 interrupt thread's interrupt source.
 109 The functions receive the vector corresponding to the thread's interrupt
 110 source as their only argument.
 111 The remaining arguments form a
 112 .Xr printf 9
 113 argument list that is used to build the base name of the new ithread.
 114 The full name of an interrupt thread is formed by concatenating the base
 115 name of an interrupt thread with the names of all of its interrupt handlers.
 116 .Pp
 117 The
 118 .Fn ithread_destroy
 119 function destroys a previously created interrupt thread by releasing its
 120 resources and arranging for the backing kernel thread to terminate.
 121 An interrupt thread can only be destroyed if it has no handlers remaining.
 122 .Pp
 123 The
 124 .Fn ithread_add_handler
 125 function adds a new handler to an existing interrupt thread specified by
 126 .Fa ithread .
 127 The
 128 .Fa name
 129 argument specifies a name for this handler.
 130 The
 131 .Fa handler
 132 and
 133 .Fa arg
 134 arguments provide the function to execute for this handler and an argument
 135 to pass to it.
 136 The
 137 .Fa pri
 138 argument specifies the priority of this handler and is used both in sorting
 139 it in relation to the other handlers for this thread and to specify the
 140 priority of the backing kernel thread.
 141 The
 142 .Fa flags
 143 argument can be used to specify properties of this handler as defined in
 144 .In sys/bus.h .
 145 If
 146 .Fa cookiep
 147 is not
 148 .Dv NULL ,
 149 then it will be assigned a cookie that can be used later to remove this
 150 handler.
 151 .Pp
 152 The
 153 .Fn ithread_remove_handler
 154 removes a handler from an interrupt thread.
 155 The
 156 .Fa cookie
 157 argument specifies the handler to remove from its thread.
 158 .Pp
 159 The
 160 .Fn ithread_schedule
 161 function schedules an interrupt thread to run.
 162 If the
 163 .Fa do_switch
 164 argument is non-zero and the interrupt thread is idle, then a context switch
 165 will be forced after putting the interrupt thread on the run queue.
 166 .Pp
 167 The
 168 .Fn ithread_priority
 169 function translates the
 170 .Dv INTR_TYPE_*
 171 interrupt flags into interrupt handler priorities.
 172 .Pp
 173 The interrupt flags not related to the type of a particular interrupt
 174 .Pq Dv INTR_TYPE_*
 175 can be used to specify additional properties of both hardware and software
 176 interrupt handlers.
 177 The
 178 .Dv INTR_EXCL
 179 flag specifies that this handler cannot share an interrupt thread with
 180 another handler.
 181 The
 182 .Dv INTR_MPSAFE
 183 flag specifies that this handler is MP safe in that it does not need the
 184 Giant mutex to be held while it is executed.
 185 The
 186 .Dv INTR_ENTROPY
 187 flag specifies that the interrupt source this handler is tied to is a good
 188 source of entropy, and thus that entropy should be gathered when an interrupt
 189 from the handler's source triggers.
 190 Presently, the
 191 .Dv INTR_ENTROPY
 192 flag is not valid for software interrupt handlers.
 193 .Pp
 194 It is not permitted to sleep in an interrupt thread; hence, any memory
 195 or zone allocations in an interrupt thread should be specified with the
 196 .Dv M_NOWAIT
 197 flag set.
 198 Any allocation errors must be handled thereafter.
 199 .Sh RETURN VALUES
 200 The
 201 .Fn ithread_add_handler ,
 202 .Fn ithread_create ,
 203 .Fn ithread_destroy ,
 204 .Fn ithread_remove_handler ,
 205 and
 206 .Fn ithread_schedule
 207 functions return zero on success and non-zero on failure.
 208 The
 209 .Fn ithread_priority
 210 function returns a process priority corresponding to the passed in interrupt
 211 flags.
 212 .Sh EXAMPLES
 213 The
 214 .Fn swi_add
 215 function demonstrates the use of
 216 .Fn ithread_create
 217 and
 218 .Fn ithread_add_handler .
 219 .Bd -literal -offset indent
 220 int
 221 swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
 222             void *arg, int pri, enum intr_type flags, void **cookiep)
 223 {
 224         struct proc *p;
 225         struct ithd *ithd;
 226         int error;
 227
 228         if (flags & INTR_ENTROPY)
 229                 return (EINVAL);
 230
 231         ithd = (ithdp != NULL) ? *ithdp : NULL;
 232
 233         if (ithd != NULL) {
 234                 if ((ithd->it_flags & IT_SOFT) == 0)
 235                         return(EINVAL);
 236         } else {
 237                 error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
 238                     "swi%d:", pri);
 239                 if (error)
 240                         return (error);
 241
 242                 if (ithdp != NULL)
 243                         *ithdp = ithd;
 244         }
 245         return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
 246                     flags, cookiep));
 247 }
 248 .Ed
 249 .Sh ERRORS
 250 The
 251 .Fn ithread_add_handler
 252 function will fail if:
 253 .Bl -tag -width Er
 254 .It Bq Er EINVAL
 255 Any of the
 256 .Fa ithread ,
 257 .Fa handler ,
 258 or
 259 .Fa name
 260 arguments are
 261 .Dv NULL .
 262 .It Bq Er EINVAL
 263 The
 264 .Dv INTR_EXCL
 265 flag is specified and the interrupt thread
 266 .Fa ithread
 267 already has at least one handler, or the interrupt thread
 268 .Fa ithread
 269 already has an exclusive handler.
 270 .It Bq Er ENOMEM
 271 Could not allocate needed memory for this handler.
 272 .El
 273 .Pp
 274 The
 275 .Fn ithread_create
 276 function will fail if:
 277 .Bl -tag -width Er
 278 .It Bq Er EAGAIN
 279 The system-imposed limit on the total
 280 number of processes under execution would be exceeded.
 281 The limit is given by the
 282 .Xr sysctl 3
 283 MIB variable
 284 .Dv KERN_MAXPROC .
 285 .It Bq Er EINVAL
 286 A flag other than
 287 .Dv IT_SOFT
 288 was specified in the
 289 .Fa flags
 290 parameter.
 291 .It Bq Er ENOMEM
 292 Could not allocate needed memory for this interrupt thread.
 293 .El
 294 .Pp
 295 The
 296 .Fn ithread_destroy
 297 function will fail if:
 298 .Bl -tag -width Er
 299 .It Bq Er EINVAL
 300 The
 301 .Fa ithread
 302 argument is
 303 .Dv NULL .
 304 .It Bq Er EINVAL
 305 The interrupt thread pointed to by
 306 .Fa ithread
 307 has at least one handler.
 308 .El
 309 .Pp
 310 The
 311 .Fn ithread_remove_handler
 312 function will fail if:
 313 .Bl -tag -width Er
 314 .It Bq Er EINVAL
 315 The
 316 .Fa cookie
 317 argument is
 318 .Dv NULL .
 319 .El
 320 .Pp
 321 The
 322 .Fn ithread_schedule
 323 function will fail if:
 324 .Bl -tag -width Er
 325 .It Bq Er EINVAL
 326 The
 327 .Fa ithread
 328 argument is
 329 .Dv NULL .
 330 .It Bq Er EINVAL
 331 The interrupt thread pointed to by
 332 .Fa ithread
 333 has no interrupt handlers.
 334 .El
 335 .Sh SEE ALSO
 336 .Xr kthread 9 ,
 337 .Xr malloc 9 ,
 338 .Xr swi 9 ,
 339 .Xr uma 9
 340 .Sh HISTORY
 341 Interrupt threads and their corresponding API first appeared in
 342 .Fx 5.0 .
 343 .Sh BUGS
 344 Currently
 345 .Vt struct ithd
 346 represents both an interrupt source and an interrupt thread.
 347 There should be a separate
 348 .Vt struct isrc
 349 that contains a vector number, enable and disable functions, etc.\& that
 350 an ithread holds a reference to.