share/man/man9/ithread.9

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