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: src/share/man/man9/BUS_SETUP_INTR.9,v 1.20 2007/03/01 14:33:29 ru Exp $
  26 .\"
  27 .Dd September 7, 2012
  28 .Dt BUS_SETUP_INTR 9
  29 .Os
  30 .Sh NAME
  31 .Nm BUS_SETUP_INTR ,
  32 .Nm bus_setup_intr ,
  33 .Nm bus_setup_intr_descr ,
  34 .Nm BUS_TEARDOWN_INTR ,
  35 .Nm bus_teardown_intr
  36 .Nd create, attach and teardown an interrupt handler
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/bus.h
  40 .Ft int
  41 .Fo BUS_SETUP_INTR
  42 .Fa "device_t dev" "device_t child" "struct resource *irq" "int flags"
  43 .Fa "driver_intr_t *intr" "void *arg" "void **cookiep"
  44 .Fa "lwkt_serialize_t serializer" "const char *desc"
  45 .Fc
  46 .Ft int
  47 .Fo bus_setup_intr
  48 .Fa "device_t dev" "struct resource *r" "int flags" "driver_intr_t handler"
  49 .Fa "void *arg" "void **cookiep" "lwkt_serialize_t serializer"
  50 .Fc
  51 .Ft int
  52 .Fo bus_setup_intr_descr
  53 .Fa "device_t dev" "struct resource *r" "int flags" "driver_intr_t handler"
  54 .Fa "void *arg" "void **cookiep" "lwkt_serialize_t serializer"
  55 .Fa "const char *desc"
  56 .Fc
  57 .Ft int
  58 .Fo BUS_TEARDOWN_INTR
  59 .Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie"
  60 .Fc
  61 .Ft int
  62 .Fn bus_teardown_intr "device_t dev" "struct resource *r" "void *cookie"
  63 .Sh DESCRIPTION
  64 The
  65 .Fn BUS_SETUP_INTR
  66 method
  67 will create and attach an interrupt handler to an interrupt
  68 previously allocated by the resource manager's
  69 .Xr BUS_ALLOC_RESOURCE 9
  70 method.
  71 The defined handler
  72 will be called with the value
  73 .Fa arg
  74 as its only argument.
  75 .Pp
  76 The
  77 .Fa cookiep
  78 argument is a pointer to a
  79 .Vt "void *"
  80 that
  81 .Fn BUS_SETUP_INTR
  82 will write a cookie for the parent bus' use to if it is successful in
  83 establishing an interrupt.
  84 Driver writers may assume that this cookie will be non-zero.
  85 The nexus driver will write 0 on failure to
  86 .Fa cookiep .
  87 .Pp
  88 The
  89 .Fa flags
  90 are found in
  91 .In sys/bus.h
  92 and tell the interrupt handlers about certain
  93 device driver characteristics and are typically either
  94 .Li 0
  95 or
  96 .Dv INTR_MPSAFE .
  97 If
  98 .Dv INTR_MPSAFE
  99 is specified the kernel is free to call the interrupt handler without
 100 holding the MP lock.
 101 .Dv INTR_FAST
 102 is also sometimes specified and allows the
 103 interrupt handler to be directly called from the context of the thread
 104 being interrupted, but is not recommended for most drivers.
 105 Other interrupt flags exist for special purposes.
 106 .Pp
 107 If
 108 .Fa serializer
 109 is non-NULL the interrupt handler will be called with the serializer held.
 110 The serializer replaces the obsolete SPL calls that are no longer relevant on
 111 SMP systems.
 112 Driver code can obtain the same serializer to interlock against
 113 the driver interrupt.
 114 The serializer also has enablement and disablement
 115 features which mainline driver code can use to avoid races between interrupt
 116 disablement and delayed interrupts executing from the device's interrupt
 117 thread.
 118 .Pp
 119 .Fa desc
 120 can be used to describe the interrupt handler, which is particularly useful
 121 for devices that use multiple interrupts. If it is NULL, the device name
 122 will be used instead.
 123 .Pp
 124 The interrupt handler will be detached by
 125 .Fn BUS_TEARDOWN_INTR .
 126 The
 127 .Fa cookie
 128 needs to be passed to
 129 .Fn BUS_TEARDOWN_INTR
 130 in order to tear down the correct interrupt handler.
 131 Once
 132 .Fn BUS_TEARDOWN_INTR
 133 returns, it is guaranteed that the interrupt function is not active and
 134 will no longer be called.
 135 .Pp
 136 The lowercase versions
 137 .Fn bus_setup_intr ,
 138 .Fn bus_setup_intr_descr
 139 and
 140 .Fn bus_teardown_intr
 141 are convenience functions to make it easier for drivers to use the
 142 resource-management functions.
 143 All they do is hide indirection through the parent's method table,
 144 making for slightly less wordy code.
 145 .Sh RETURN VALUES
 146 Zero is returned on success,
 147 otherwise an appropriate error is returned.
 148 .Sh SEE ALSO
 149 .Xr device 9 ,
 150 .Xr driver 9 ,
 151 .Xr serializer 9
 152 .Sh AUTHORS
 153 .An -nosplit
 154 This manual page was written by
 155 .An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org
 156 based on the manual pages for
 157 .Fn BUS_CREATE_INTR
 158 and
 159 .Fn BUS_CONNECT_INTR
 160 written by
 161 .An Doug Rabson Aq Mt dfr@FreeBSD.org .