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