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 March 25, 2016 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 64The 65.Fn BUS_SETUP_INTR 66method 67will create and attach an interrupt handler to an interrupt 68previously allocated by the resource manager's 69.Xr BUS_ALLOC_RESOURCE 9 70method. 71The defined handler 72will be called with the value 73.Fa arg 74as its only argument. 75.Pp 76The 77.Fa cookiep 78argument is a pointer to a 79.Vt "void *" 80that 81.Fn BUS_SETUP_INTR 82will write a cookie for the parent bus' use to if it is successful in 83establishing an interrupt. 84Driver writers may assume that this cookie will be non-zero. 85The nexus driver will write 0 on failure to 86.Fa cookiep . 87.Pp 88The 89.Fa flags 90are found in 91.In sys/bus.h 92and tell the interrupt handlers about certain 93device driver characteristics and are typically either 94.Li 0 95or 96.Dv INTR_MPSAFE . 97If 98.Dv INTR_MPSAFE 99is specified the kernel is free to call the interrupt handler without 100holding the MP lock. 101Other interrupt flags exist for special purposes. 102If 103.Dv INTR_NOPOLL 104is specified, the interrupt handler is not executed by the emergency 105interrupt polling code. 106.Pp 107If 108.Fa serializer 109is non-NULL the interrupt handler will be called with the serializer held. 110The serializer replaces the obsolete SPL calls that are no longer relevant on 111SMP systems. 112Driver code can obtain the same serializer to interlock against 113the driver interrupt. 114The serializer also has enablement and disablement 115features which mainline driver code can use to avoid races between interrupt 116disablement and delayed interrupts executing from the device's interrupt 117thread. 118.Pp 119.Fa desc 120can be used to describe the interrupt handler, which is particularly useful 121for devices that use multiple interrupts. If it is NULL, the device name 122will be used instead. 123.Pp 124The interrupt handler will be detached by 125.Fn BUS_TEARDOWN_INTR . 126The 127.Fa cookie 128needs to be passed to 129.Fn BUS_TEARDOWN_INTR 130in order to tear down the correct interrupt handler. 131Once 132.Fn BUS_TEARDOWN_INTR 133returns, it is guaranteed that the interrupt function is not active and 134will no longer be called. 135.Pp 136The lowercase versions 137.Fn bus_setup_intr , 138.Fn bus_setup_intr_descr 139and 140.Fn bus_teardown_intr 141are convenience functions to make it easier for drivers to use the 142resource-management functions. 143All they do is hide indirection through the parent's method table, 144making for slightly less wordy code. 145.Sh RETURN VALUES 146Zero is returned on success, 147otherwise 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 154This manual page was written by 155.An Jeroen Ruigrok van der Werven Aq Mt asmodai@FreeBSD.org 156based on the manual pages for 157.Fn BUS_CREATE_INTR 158and 159.Fn BUS_CONNECT_INTR 160written by 161.An Doug Rabson Aq Mt dfr@FreeBSD.org . 162