Author: jhb
Date: Thu Oct 15 14:54:35 2009
New Revision: 198134
URL: http://svn.freebsd.org/changeset/base/198134
Log:
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
Added:
head/share/man/man9/BUS_DESCRIBE_INTR.9 (contents, props changed)
Modified:
head/share/man/man9/Makefile
head/sys/amd64/amd64/intr_machdep.c
head/sys/amd64/amd64/nexus.c
head/sys/amd64/include/intr_machdep.h
head/sys/i386/i386/intr_machdep.c
head/sys/i386/i386/nexus.c
head/sys/i386/include/intr_machdep.h
head/sys/kern/bus_if.m
head/sys/kern/kern_intr.c
head/sys/kern/subr_bus.c
head/sys/sys/bus.h
head/sys/sys/interrupt.h
Added: head/share/man/man9/BUS_DESCRIBE_INTR.9
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ head/share/man/man9/BUS_DESCRIBE_INTR.9 Thu Oct 15 14:54:35 2009
(r198134)
@@ -0,0 +1,104 @@
+.\" -*- nroff -*-
+.\"
+.\" Copyright (c) 2009 Advanced Computing Technologies LLC
+.\" Written by: John H. Baldwin <j...@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.
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Thu Oct 15 14:39:59 2009
(r198133)
+++ head/share/man/man9/Makefile Thu Oct 15 14:54:35 2009
(r198134)
@@ -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 \
Modified: head/sys/amd64/amd64/intr_machdep.c
==============================================================================
--- head/sys/amd64/amd64/intr_machdep.c Thu Oct 15 14:39:59 2009
(r198133)
+++ head/sys/amd64/amd64/intr_machdep.c Thu Oct 15 14:54:35 2009
(r198134)
@@ -466,6 +466,23 @@ intr_bind(u_int vector, u_char cpu)
return (intr_event_bind(isrc->is_event, cpu));
}
+/* Add a description to an active interrupt handler. */
+int
+intr_describe(u_int vector, void *ih, const char *descr)
+{
+ struct intsrc *isrc;
+ int error;
+
+ isrc = intr_lookup_source(vector);
+ if (isrc == NULL)
+ return (EINVAL);
+ error = intr_event_describe_handler(isrc->is_event, ih, descr);
+ if (error)
+ return (error);
+ intrcnt_updatename(isrc);
+ return (0);
+}
+
/*
* Add a CPU to our mask of valid CPUs that can be destinations of
* interrupts.
Modified: head/sys/amd64/amd64/nexus.c
==============================================================================
--- head/sys/amd64/amd64/nexus.c Thu Oct 15 14:39:59 2009
(r198133)
+++ head/sys/amd64/amd64/nexus.c Thu Oct 15 14:54:35 2009
(r198134)
@@ -92,6 +92,9 @@ static int nexus_bind_intr(device_t, dev
#endif
static int nexus_config_intr(device_t, int, enum intr_trigger,
enum intr_polarity);
+static int nexus_describe_intr(device_t dev, device_t child,
+ struct resource *irq, void *cookie,
+ const char *descr);
static int nexus_activate_resource(device_t, device_t, int, int,
struct resource *);
static int nexus_deactivate_resource(device_t, device_t, int, int,
@@ -135,6 +138,7 @@ static device_method_t nexus_methods[] =
DEVMETHOD(bus_bind_intr, nexus_bind_intr),
#endif
DEVMETHOD(bus_config_intr, nexus_config_intr),
+ DEVMETHOD(bus_describe_intr, nexus_describe_intr),
DEVMETHOD(bus_get_resource_list, nexus_get_reslist),
DEVMETHOD(bus_set_resource, nexus_set_resource),
DEVMETHOD(bus_get_resource, nexus_get_resource),
@@ -479,6 +483,14 @@ nexus_config_intr(device_t dev, int irq,
return (intr_config_intr(irq, trig, pol));
}
+static int
+nexus_describe_intr(device_t dev, device_t child, struct resource *irq,
+ void *cookie, const char *descr)
+{
+
+ return (intr_describe(rman_get_start(irq), cookie, descr));
+}
+
static struct resource_list *
nexus_get_reslist(device_t dev, device_t child)
{
Modified: head/sys/amd64/include/intr_machdep.h
==============================================================================
--- head/sys/amd64/include/intr_machdep.h Thu Oct 15 14:39:59 2009
(r198133)
+++ head/sys/amd64/include/intr_machdep.h Thu Oct 15 14:54:35 2009
(r198134)
@@ -151,6 +151,7 @@ int intr_bind(u_int vector, u_char cpu);
#endif
int intr_config_intr(int vector, enum intr_trigger trig,
enum intr_polarity pol);
+int intr_describe(u_int vector, void *ih, const char *descr);
void intr_execute_handlers(struct intsrc *isrc, struct trapframe *frame);
u_int intr_next_cpu(void);
struct intsrc *intr_lookup_source(int vector);
Modified: head/sys/i386/i386/intr_machdep.c
==============================================================================
--- head/sys/i386/i386/intr_machdep.c Thu Oct 15 14:39:59 2009
(r198133)
+++ head/sys/i386/i386/intr_machdep.c Thu Oct 15 14:54:35 2009
(r198134)
@@ -432,6 +432,23 @@ intr_bind(u_int vector, u_char cpu)
return (intr_event_bind(isrc->is_event, cpu));
}
+/* Add a description to an active interrupt handler. */
+int
+intr_describe(u_int vector, void *ih, const char *descr)
+{
+ struct intsrc *isrc;
+ int error;
+
+ isrc = intr_lookup_source(vector);
+ if (isrc == NULL)
+ return (EINVAL);
+ error = intr_event_describe_handler(isrc->is_event, ih, descr);
+ if (error)
+ return (error);
+ intrcnt_updatename(isrc);
+ return (0);
+}
+
/*
* Add a CPU to our mask of valid CPUs that can be destinations of
* interrupts.
Modified: head/sys/i386/i386/nexus.c
==============================================================================
--- head/sys/i386/i386/nexus.c Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/i386/i386/nexus.c Thu Oct 15 14:54:35 2009 (r198134)
@@ -96,6 +96,9 @@ static int nexus_bind_intr(device_t, dev
#endif
static int nexus_config_intr(device_t, int, enum intr_trigger,
enum intr_polarity);
+static int nexus_describe_intr(device_t dev, device_t child,
+ struct resource *irq, void *cookie,
+ const char *descr);
static int nexus_activate_resource(device_t, device_t, int, int,
struct resource *);
static int nexus_deactivate_resource(device_t, device_t, int, int,
@@ -141,6 +144,7 @@ static device_method_t nexus_methods[] =
DEVMETHOD(bus_bind_intr, nexus_bind_intr),
#endif
DEVMETHOD(bus_config_intr, nexus_config_intr),
+ DEVMETHOD(bus_describe_intr, nexus_describe_intr),
DEVMETHOD(bus_get_resource_list, nexus_get_reslist),
DEVMETHOD(bus_set_resource, nexus_set_resource),
DEVMETHOD(bus_get_resource, nexus_get_resource),
@@ -526,6 +530,14 @@ nexus_config_intr(device_t dev, int irq,
return (intr_config_intr(irq, trig, pol));
}
+static int
+nexus_describe_intr(device_t dev, device_t child, struct resource *irq,
+ void *cookie, const char *descr)
+{
+
+ return (intr_describe(rman_get_start(irq), cookie, descr));
+}
+
static struct resource_list *
nexus_get_reslist(device_t dev, device_t child)
{
Modified: head/sys/i386/include/intr_machdep.h
==============================================================================
--- head/sys/i386/include/intr_machdep.h Thu Oct 15 14:39:59 2009
(r198133)
+++ head/sys/i386/include/intr_machdep.h Thu Oct 15 14:54:35 2009
(r198134)
@@ -138,6 +138,7 @@ int intr_bind(u_int vector, u_char cpu);
#endif
int intr_config_intr(int vector, enum intr_trigger trig,
enum intr_polarity pol);
+int intr_describe(u_int vector, void *ih, const char *descr);
void intr_execute_handlers(struct intsrc *isrc, struct trapframe *frame);
u_int intr_next_cpu(void);
struct intsrc *intr_lookup_source(int vector);
Modified: head/sys/kern/bus_if.m
==============================================================================
--- head/sys/kern/bus_if.m Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/kern/bus_if.m Thu Oct 15 14:54:35 2009 (r198134)
@@ -509,7 +509,6 @@ METHOD int bind_intr {
int _cpu;
} DEFAULT bus_generic_bind_intr;
-
/**
* @brief Allow (bus) drivers to specify the trigger mode and polarity
* of the specified interrupt.
@@ -527,6 +526,25 @@ METHOD int config_intr {
} DEFAULT bus_generic_config_intr;
/**
+ * @brief Allow drivers to associate a description with an active
+ * interrupt handler.
+ *
+ * @param _dev the parent device of @p _child
+ * @param _child the device which allocated the resource
+ * @param _irq the resource representing the interrupt
+ * @param _cookie the cookie value returned when the interrupt
+ * was originally registered
+ * @param _descr the description to associate with the interrupt
+ */
+METHOD int describe_intr {
+ device_t _dev;
+ device_t _child;
+ struct resource *_irq;
+ void *_cookie;
+ const char *_descr;
+} DEFAULT bus_generic_describe_intr;
+
+/**
* @brief Notify a (bus) driver about a child that the hints mechanism
* believes it has discovered.
*
Modified: head/sys/kern/kern_intr.c
==============================================================================
--- head/sys/kern/kern_intr.c Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/kern/kern_intr.c Thu Oct 15 14:54:35 2009 (r198134)
@@ -524,7 +524,7 @@ intr_event_add_handler(struct intr_event
ih->ih_filter = filter;
ih->ih_handler = handler;
ih->ih_argument = arg;
- ih->ih_name = name;
+ strlcpy(ih->ih_name, name, sizeof(ih->ih_name));
ih->ih_event = ie;
ih->ih_pri = pri;
if (flags & INTR_EXCL)
@@ -597,7 +597,7 @@ intr_event_add_handler(struct intr_event
ih->ih_filter = filter;
ih->ih_handler = handler;
ih->ih_argument = arg;
- ih->ih_name = name;
+ strlcpy(ih->ih_name, name, sizeof(ih->ih_name));
ih->ih_event = ie;
ih->ih_pri = pri;
if (flags & INTR_EXCL)
@@ -665,6 +665,61 @@ intr_event_add_handler(struct intr_event
#endif
/*
+ * Append a description preceded by a ':' to the name of the specified
+ * interrupt handler.
+ */
+int
+intr_event_describe_handler(struct intr_event *ie, void *cookie,
+ const char *descr)
+{
+ struct intr_handler *ih;
+ size_t space;
+ char *start;
+
+ mtx_lock(&ie->ie_lock);
+#ifdef INVARIANTS
+ TAILQ_FOREACH(ih, &ie->ie_handlers, ih_next) {
+ if (ih == cookie)
+ break;
+ }
+ if (ih == NULL) {
+ mtx_unlock(&ie->ie_lock);
+ panic("handler %p not find in interrupt event %p", cookie, ie);
+ }
+#endif
+ ih = cookie;
+
+ /*
+ * Look for an existing description by checking for an
+ * existing ":". This assumes device names do not include
+ * colons. If one is found, prepare to insert the new
+ * description at that point. If one is not found, find the
+ * end of the name to use as the insertion point.
+ */
+ start = index(ih->ih_name, ':');
+ if (start == NULL)
+ start = index(ih->ih_name, 0);
+
+ /*
+ * See if there is enough remaining room in the string for the
+ * description + ":". The "- 1" leaves room for the trailing
+ * '\0'. The "+ 1" accounts for the colon.
+ */
+ space = sizeof(ih->ih_name) - (start - ih->ih_name) - 1;
+ if (strlen(descr) + 1 > space) {
+ mtx_unlock(&ie->ie_lock);
+ return (ENOSPC);
+ }
+
+ /* Append a colon followed by the description. */
+ *start = ':';
+ strcpy(start + 1, descr);
+ intr_event_update(ie);
+ mtx_unlock(&ie->ie_lock);
+ return (0);
+}
+
+/*
* Return the ie_source field from the intr_event an intr_handler is
* associated with.
*/
Modified: head/sys/kern/subr_bus.c
==============================================================================
--- head/sys/kern/subr_bus.c Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/kern/subr_bus.c Thu Oct 15 14:54:35 2009 (r198134)
@@ -3520,6 +3520,24 @@ bus_generic_config_intr(device_t dev, in
}
/**
+ * @brief Helper function for implementing BUS_DESCRIBE_INTR().
+ *
+ * This simple implementation of BUS_DESCRIBE_INTR() simply calls the
+ * BUS_DESCRIBE_INTR() method of the parent of @p dev.
+ */
+int
+bus_generic_describe_intr(device_t dev, device_t child, struct resource *irq,
+ void *cookie, const char *descr)
+{
+
+ /* Propagate up the bus hierarchy until someone handles it. */
+ if (dev->parent)
+ return (BUS_DESCRIBE_INTR(dev->parent, child, irq, cookie,
+ descr));
+ return (EINVAL);
+}
+
+/**
* @brief Helper function for implementing BUS_GET_DMA_TAG().
*
* This simple implementation of BUS_GET_DMA_TAG() simply calls the
@@ -3824,6 +3842,28 @@ bus_bind_intr(device_t dev, struct resou
}
/**
+ * @brief Wrapper function for BUS_DESCRIBE_INTR().
+ *
+ * This function first formats the requested description into a
+ * temporary buffer and then calls the BUS_DESCRIBE_INTR() method of
+ * the parent of @p dev.
+ */
+int
+bus_describe_intr(device_t dev, struct resource *irq, void *cookie,
+ const char *fmt, ...)
+{
+ char descr[MAXCOMLEN];
+ va_list ap;
+
+ if (dev->parent == NULL)
+ return (EINVAL);
+ va_start(ap, fmt);
+ vsnprintf(descr, sizeof(descr), fmt, ap);
+ va_end(ap);
+ return (BUS_DESCRIBE_INTR(dev->parent, dev, irq, cookie, descr));
+}
+
+/**
* @brief Wrapper function for BUS_SET_RESOURCE().
*
* This function simply calls the BUS_SET_RESOURCE() method of the
Modified: head/sys/sys/bus.h
==============================================================================
--- head/sys/sys/bus.h Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/sys/bus.h Thu Oct 15 14:54:35 2009 (r198134)
@@ -292,6 +292,9 @@ int bus_generic_bind_intr(device_t dev,
int bus_generic_child_present(device_t dev, device_t child);
int bus_generic_config_intr(device_t, int, enum intr_trigger,
enum intr_polarity);
+int bus_generic_describe_intr(device_t dev, device_t child,
+ struct resource *irq, void *cookie,
+ const char *descr);
int bus_generic_deactivate_resource(device_t dev, device_t child, int type,
int rid, struct resource *r);
int bus_generic_detach(device_t dev);
@@ -363,6 +366,8 @@ int bus_setup_intr(device_t dev, struct
void *arg, void **cookiep);
int bus_teardown_intr(device_t dev, struct resource *r, void *cookie);
int bus_bind_intr(device_t dev, struct resource *r, int cpu);
+int bus_describe_intr(device_t dev, struct resource *irq, void *cookie,
+ const char *fmt, ...);
int bus_set_resource(device_t dev, int type, int rid,
u_long start, u_long count);
int bus_get_resource(device_t dev, int type, int rid,
Modified: head/sys/sys/interrupt.h
==============================================================================
--- head/sys/sys/interrupt.h Thu Oct 15 14:39:59 2009 (r198133)
+++ head/sys/sys/interrupt.h Thu Oct 15 14:54:35 2009 (r198134)
@@ -47,7 +47,7 @@ struct intr_handler {
driver_intr_t *ih_handler; /* Threaded handler function. */
void *ih_argument; /* Argument to pass to handlers. */
int ih_flags;
- const char *ih_name; /* Name of handler. */
+ char ih_name[MAXCOMLEN]; /* Name of handler. */
struct intr_event *ih_event; /* Event we are connected to. */
int ih_need; /* Needs service. */
TAILQ_ENTRY(intr_handler) ih_next; /* Next handler for this event. */
@@ -172,6 +172,8 @@ int intr_event_destroy(struct intr_event
void intr_event_execute_handlers(struct proc *p, struct intr_event *ie);
int intr_event_handle(struct intr_event *ie, struct trapframe *frame);
int intr_event_remove_handler(void *cookie);
+int intr_event_describe_handler(struct intr_event *ie, void *cookie,
+ const char *descr);
int intr_getaffinity(int irq, void *mask);
void *intr_handler_source(void *cookie);
int intr_setaffinity(int irq, void *mask);
_______________________________________________
svn-src-all@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/svn-src-all
To unsubscribe, send any mail to "svn-src-all-unsubscr...@freebsd.org"
