1.\" -*- nroff -*- 2.\" 3.\" Copyright (c) 2009 Hudson River Trading LLC 4.\" Written by: John H. Baldwin <jhb@FreeBSD.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd December 9, 2015 29.Dt BUS_DESCRIBE_INTR 9 30.Os 31.Sh NAME 32.Nm BUS_DESCRIBE_INTR , 33.Nm bus_describe_intr 34.Nd "associate a description with an active interrupt handler" 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/bus.h 38.Ft int 39.Fo BUS_DESCRIBE_INTR 40.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie" 41.Fa "const char *descr" 42.Fc 43.Ft int 44.Fo bus_describe_intr 45.Fa "device_t dev" "struct resource *irq" "void *cookie" "const char *fmt" 46.Fa ... 47.Fc 48.Sh DESCRIPTION 49The 50.Fn BUS_DESCRIBE_INTR 51method associates a description with an active interrupt handler. 52The 53.Fa cookie 54parameter must be the value returned by a successful call to 55.Xr BUS_SETUP_INTR 9 56for the interrupt 57.Fa irq . 58.Pp 59The 60.Fn bus_describe_intr 61function is a simple wrapper around 62.Fn BUS_DESCRIBE_INTR . 63As a convenience, 64.Fn bus_describe_intr 65allows the caller to use 66.Xr printf 9 67style formatting to build the description string using 68.Fa fmt . 69.Pp 70When an interrupt handler is established by 71.Xr BUS_SETUP_INTR 9 , 72the handler is named after the device the handler is established for. 73This name is then used in various places such as interrupt statistics 74displayed by 75.Xr systat 1 76and 77.Xr vmstat 8 . 78For devices that use a single interrupt, 79the device name is sufficiently unique to identify the interrupt handler. 80However, for devices that use multiple interrupts it can be useful to 81distinguish the interrupt handlers. 82When a description is set for an active interrupt handler, 83a colon followed by the description is appended to the device name to form 84the interrupt handler name. 85.Sh RETURN VALUES 86Zero is returned on success, otherwise an appropriate error is returned. 87.Sh SEE ALSO 88.Xr systat 1 , 89.Xr vmstat 8 , 90.Xr BUS_SETUP_INTR 9 , 91.Xr device 9 , 92.Xr printf 9 93.Sh HISTORY 94The 95.Fn BUS_DESCRIBE_INTR 96method and 97.Fn bus_describe_intr 98functions first appeared in 99.Fx 8.1 . 100.Sh BUGS 101It is not currently possible to remove a description from an active interrupt 102handler. 103