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