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