From 45688ed39df1a016dde3d3f3cb4f19e562a683c2 Mon Sep 17 00:00:00 2001 From: jhb Date: Thu, 15 Oct 2009 14:54:35 +0000 Subject: 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 --- share/man/man9/BUS_DESCRIBE_INTR.9 | 104 +++++++++++++++++++++++++++++++++++++ share/man/man9/Makefile | 2 + 2 files changed, 106 insertions(+) create mode 100644 share/man/man9/BUS_DESCRIBE_INTR.9 (limited to 'share/man') 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 +.\" 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 \ -- cgit v1.1