share/man/man9/BUS_SETUP_INTR.9

   1 .\" Copyright (c) 2000 Jeroen Ruigrok van der Werven
   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 March 1, 2007
  28 .Dt BUS_SETUP_INTR 9
  29 .Os
  30 .Sh NAME
  31 .Nm BUS_SETUP_INTR ,
  32 .Nm bus_setup_intr ,
  33 .Nm BUS_TEARDOWN_INTR ,
  34 .Nm bus_teardown_intr
  35 .Nd create, attach and teardown an interrupt handler
  36 .Sh SYNOPSIS
  37 .In sys/param.h
  38 .In sys/bus.h
  39 .Ft int
  40 .Fo BUS_SETUP_INTR
  41 .Fa "device_t dev" "device_t child" "struct resource *irq" "int flags"
  42 .Fa "driver_filter_t *filter" "driver_intr_t *ithread" "void *arg"
  43 .Fa "void **cookiep"
  44 .Fc
  45 .Ft int
  46 .Fo bus_setup_intr
  47 .Fa "device_t dev" "struct resource *r" "int flags"
  48 .Fa "driver_filter_t filter" "driver_intr_t ithread" "void *arg"
  49 .Fa "void **cookiep"
  50 .Fc
  51 .Ft int
  52 .Fo BUS_TEARDOWN_INTR
  53 .Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookiep"
  54 .Fc
  55 .Ft int
  56 .Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookiep"
  57 .Sh DESCRIPTION
  58 The
  59 .Fn BUS_SETUP_INTR
  60 method
  61 will create and attach an interrupt handler to an interrupt
  62 previously allocated by the resource manager's
  63 .Xr BUS_ALLOC_RESOURCE 9
  64 method.
  65 The
  66 .Fa flags
  67 are found in
  68 .In sys/bus.h ,
  69 and give the broad category of interrupt.
  70 The
  71 .Fa flags
  72 also tell the interrupt handlers about certain
  73 device driver characteristics.
  74 .Dv INTR_EXCL
  75 marks the handler as being
  76 an exclusive handler for this interrupt.
  77 .Dv INTR_MPSAFE
  78 tells the scheduler that the interrupt handler
  79 is well behaved in a preemptive environment
  80 (``SMP safe''),
  81 and does not need
  82 to be protected by the ``Giant Lock'' mutex.
  83 .Dv INTR_ENTROPY
  84 marks the interrupt as being a good source of entropy -
  85 this may be used by the entropy device
  86 .Pa /dev/random .
  87 .Pp
  88 To define a time-critical handler (previously known as
  89 .Dv INTR_FAST )
  90 that will not execute any potentially blocking operation, use the
  91 .Fa filter
  92 argument.
  93 Otherwise, use the
  94 .Fa ithread
  95 argument.
  96 The defined handler
  97 will be called with the value
  98 .Fa arg
  99 as its only argument.
 100 .Pp
 101 The
 102 .Fa cookiep
 103 argument is a pointer to a
 104 .Vt "void *"
 105 that
 106 .Fn BUS_SETUP_INTR
 107 will write a cookie for the parent bus' use to if it is successful in
 108 establishing an interrupt.
 109 Driver writers may assume that this cookie will be non-zero.
 110 The nexus driver will write 0 on failure to
 111 .Fa cookiep .
 112 .Pp
 113 The interrupt handler will be detached by
 114 .Fn BUS_TEARDOWN_INTR .
 115 The cookie needs to be passed to
 116 .Fn BUS_TEARDOWN_INTR
 117 in order to tear down the correct interrupt handler.
 118 Once
 119 .Fn BUS_TEARDOWN_INTR
 120 returns, it is guaranteed that the interrupt function is not active and
 121 will no longer be called.
 122 .Pp
 123 Mutexes are not allowed to be held across calls to these functions.
 124 .Sh RETURN VALUES
 125 Zero is returned on success,
 126 otherwise an appropriate error is returned.
 127 .Sh SEE ALSO
 128 .Xr random 4 ,
 129 .Xr device 9 ,
 130 .Xr driver 9
 131 .Sh AUTHORS
 132 .An -nosplit
 133 This manual page was written by
 134 .An Jeroen Ruigrok van der Werven
 135 .Aq asmodai@FreeBSD.org
 136 based on the manual pages for
 137 .Fn BUS_CREATE_INTR
 138 and
 139 .Fn BUS_CONNECT_INTR
 140 written by
 141 .An Doug Rabson
 142 .Aq dfr@FreeBSD.org .