Add a facility for associating optional descriptions with active interrupt

handlers.  This is primarily intended as a way to allow devices that use
multiple interrupts (e.g. MSI) to meaningfully distinguish the various
interrupt handlers.
- Add a new BUS_DESCRIBE_INTR() method to the bus interface to associate
  a description with an active interrupt handler setup by BUS_SETUP_INTR.
  It has a default method (bus_generic_describe_intr()) which simply passes
  the request up to the parent device.
- Add a bus_describe_intr() wrapper around BUS_DESCRIBE_INTR() that supports
  printf(9) style formatting using var args.
- Reserve MAXCOMLEN bytes in the intr_handler structure to hold the name of
  an interrupt handler and copy the name passed to intr_event_add_handler()
  into that buffer instead of just saving the pointer to the name.
- Add a new intr_event_describe_handler() which appends a description string
  to an interrupt handler's name.
- Implement support for interrupt descriptions on amd64 and i386 by having
  the nexus(4) driver supply a custom bus_describe_intr method that invokes
  a new intr_describe() MD routine which in turn looks up the associated
  interrupt event and invokes intr_event_describe_handler().

Requested by:	many
Reviewed by:	scottl
MFC after:	2 weeks

2 files changed, 106 insertions, 0 deletions

diff --git a/share/man/man9/BUS_DESCRIBE_INTR.9 b/share/man/man9/BUS_DESCRIBE_INTR.9
new file mode 100644
index 0000000..3da7c42
--- /dev/null
+++ b/share/man/man9/BUS_DESCRIBE_INTR.9
@@ -0,0 +1,104 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2009 Advanced Computing Technologies LLC
+.\" Written by: John H. Baldwin <jhb@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd October 14, 2009
+.Dt BUS_DESCRIBE_INTR 9
+.Os
+.Sh NAME
+.Nm BUS_DESCRIBE_INTR ,
+.Nm bus_describe_intr
+.Nd "associate a description with an active interrupt handler"
+.Sh SYNOPSIS
+.In sys/param.h
+.In sys/bus.h
+.Ft int
+.Fo BUS_BIND_INTR
+.Fa "device_t dev" "device_t child" "struct resource *irq" "void *cookie"
+.Fa "const char *descr"
+.Fc
+.Ft int
+.Fo bus_describe_intr
+.Fa "device_t dev" "struct resource *irq" "void *cookie" "const char *fmt"
+.Fa ... 
+.Fc
+.Sh DESCRIPTION
+The
+.Fn BUS_DESCRIBE_INTR
+method associates a description with an active interrupt handler.
+The
+.Fa cookie
+parameter must be the value returned by a successful call to
+.Xr BUS_SETUP_INTR 9
+for the interrupt
+.Fa irq .
+.Pp
+The
+.Fn bus_describe_intr
+function is a simple wrapper around
+.Fn BUS_DESCRIBE_INTR .
+As a convenience,
+.Fn bus_describe_intr
+allows the caller to use
+.Xr printf 9
+style formatting to build the description string using
+.Fa fmt .
+.Pp
+When an interrupt handler is established by
+.Xr BUS_SETUP_INTR 9 ,
+the handler is named after the device the handler is established for.
+This name is then used in various places such as interrupt statistics
+displayed by
+.Xr systat 1
+and
+.Xr vmstat 8 .
+For devices that use a single interrupt,
+the device name is sufficiently unique to identify the interrupt handler.
+However, for devices that use multiple interrupts it can be useful to
+distinguish the interrupt handlers.
+When a description is set for an active interrupt handler,
+a colon followed by the description is appended to the device name to form
+the interrupt handler name.
+.Sh RETURN VALUES
+Zero is returned on success, otherwise an appropriate error is returned.
+.Sh SEE ALSO
+.Xr BUS_SETUP_INTR 9 ,
+.Xr device 9 ,
+.Xr printf 9 ,
+.Xr systat 1 ,
+.Xr vmstat 8
+.Sh HISTORY
+The
+.Fn BUS_DESCRIBE_INTR
+method and
+.Fn bus_describe_intr
+functions first appeared in
+.Fx 9.0 .
+.Sh BUGS
+It is not currently possible to remove a description from an active interrupt
+handler.
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index ae8b55f..072827a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -26,6 +26,7 @@ MAN=	accept_filter.9 \
 	BUS_BIND_INTR.9 \
 	bus_child_present.9 \
 	BUS_CONFIG_INTR.9 \
+	BUS_DESCRIBE_INTR.9 \
 	bus_dma.9 \
 	bus_generic_attach.9 \
 	bus_generic_detach.9 \
@@ -405,6 +406,7 @@ MLINKS+=buf.9 bp.9
 MLINKS+=bus_activate_resource.9 bus_deactivate_resource.9
 MLINKS+=bus_alloc_resource.9 bus_alloc_resource_any.9
 MLINKS+=BUS_BIND_INTR.9 bus_bind_intr.9
+MLINKS+=BUS_DESCRIBE_INTR.9 bus_describe_intr.9
 MLINKS+=bus_dma.9 busdma.9 \
 	bus_dma.9 bus_dmamap_create.9 \
 	bus_dma.9 bus_dmamap_destroy.9 \