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_MPSAFE
 184 flag specifies that this handler is MP safe in that it does not need the
 185 Giant mutex to be held while it is executed.
 186 The
 187 .Dv INTR_ENTROPY
 188 flag specifies that the interrupt source this handler is tied to is a good
 189 source of entropy, and thus that entropy should be gathered when an interrupt
 190 from the handler's source triggers.
 191 Presently, the
 192 .Dv INTR_ENTROPY
 193 flag is not valid for software interrupt handlers.
 194 .Pp
 195 It is not permitted to sleep in an interrupt thread; hence, any memory
 196 or zone allocations in an interrupt thread should be specified with the
 197 .Dv M_NOWAIT
 198 flag set.
 199 Any allocation errors must be handled thereafter.
 200 .Sh RETURN VALUES
 201 The
 202 .Fn ithread_add_handler ,
 203 .Fn ithread_create ,
 204 .Fn ithread_destroy ,
 205 .Fn ithread_remove_handler ,
 206 and
 207 .Fn ithread_schedule
 208 functions return zero on success and non-zero on failure.
 209 The
 210 .Fn ithread_priority
 211 function returns a process priority corresponding to the passed in interrupt
 212 flags.
 213 .Sh EXAMPLES
 214 The
 215 .Fn swi_add
 216 function demonstrates the use of
 217 .Fn ithread_create
 218 and
 219 .Fn ithread_add_handler .
 220 .Bd -literal -offset indent
 221 int
 222 swi_add(struct ithd **ithdp, const char *name, driver_intr_t handler,
 223             void *arg, int pri, enum intr_type flags, void **cookiep)
 224 {
 225         struct proc *p;
 226         struct ithd *ithd;
 227         int error;
 228
 229         if (flags & INTR_ENTROPY)
 230                 return (EINVAL);
 231
 232         ithd = (ithdp != NULL) ? *ithdp : NULL;
 233
 234         if (ithd != NULL) {
 235                 if ((ithd->it_flags & IT_SOFT) == 0)
 236                         return(EINVAL);
 237         } else {
 238                 error = ithread_create(&ithd, pri, IT_SOFT, NULL, NULL,
 239                     "swi%d:", pri);
 240                 if (error)
 241                         return (error);
 242
 243                 if (ithdp != NULL)
 244                         *ithdp = ithd;
 245         }
 246         return (ithread_add_handler(ithd, name, handler, arg, pri + PI_SOFT,
 247                     flags, cookiep));
 248 }
 249 .Ed
 250 .Sh ERRORS
 251 The
 252 .Fn ithread_add_handler
 253 function will fail if:
 254 .Bl -tag -width Er
 255 .It Bq Er EINVAL
 256 Any of the
 257 .Fa ithread ,
 258 .Fa handler ,
 259 or
 260 .Fa name
 261 arguments are
 262 .Dv NULL .
 263 .It Bq Er EINVAL
 264 The
 265 .Dv INTR_EXCL
 266 flag is specified and the interrupt thread
 267 .Fa ithread
 268 already has at least one handler, or the interrupt thread
 269 .Fa ithread
 270 already has an exclusive handler.
 271 .It Bq Er ENOMEM
 272 Could not allocate needed memory for this handler.
 273 .El
 274 .Pp
 275 The
 276 .Fn ithread_create
 277 function will fail if:
 278 .Bl -tag -width Er
 279 .It Bq Er EAGAIN
 280 The system-imposed limit on the total
 281 number of processes under execution would be exceeded.
 282 The limit is given by the
 283 .Xr sysctl 3
 284 MIB variable
 285 .Dv KERN_MAXPROC .
 286 .It Bq Er EINVAL
 287 A flag other than
 288 .Dv IT_SOFT
 289 was specified in the
 290 .Fa flags
 291 parameter.
 292 .It Bq Er ENOMEM
 293 Could not allocate needed memory for this interrupt thread.
 294 .El
 295 .Pp
 296 The
 297 .Fn ithread_destroy
 298 function will fail if:
 299 .Bl -tag -width Er
 300 .It Bq Er EINVAL
 301 The
 302 .Fa ithread
 303 argument is
 304 .Dv NULL .
 305 .It Bq Er EINVAL
 306 The interrupt thread pointed to by
 307 .Fa ithread
 308 has at least one handler.
 309 .El
 310 .Pp
 311 The
 312 .Fn ithread_remove_handler
 313 function will fail if:
 314 .Bl -tag -width Er
 315 .It Bq Er EINVAL
 316 The
 317 .Fa cookie
 318 argument is
 319 .Dv NULL .
 320 .El
 321 .Pp
 322 The
 323 .Fn ithread_schedule
 324 function will fail if:
 325 .Bl -tag -width Er
 326 .It Bq Er EINVAL
 327 The
 328 .Fa ithread
 329 argument is
 330 .Dv NULL .
 331 .It Bq Er EINVAL
 332 The interrupt thread pointed to by
 333 .Fa ithread
 334 has no interrupt handlers.
 335 .El
 336 .Sh SEE ALSO
 337 .Xr kthread 9 ,
 338 .Xr malloc 9 ,
 339 .Xr swi 9 ,
 340 .Xr uma 9
 341 .Sh HISTORY
 342 Interrupt threads and their corresponding API first appeared in
 343 .Fx 5.0 .
 344 .Sh BUGS
 345 Currently
 346 .Vt struct ithd
 347 represents both an interrupt source and an interrupt thread.
 348 There should be a separate
 349 .Vt struct isrc
 350 that contains a vector number, enable and disable functions, etc.\& that
 351 an ithread holds a reference to.