105 lines
3.4 KiB
Groff
105 lines
3.4 KiB
Groff
.\" -*- 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 systat 1 ,
|
|
.Xr vmstat 8 ,
|
|
.Xr BUS_SETUP_INTR 9 ,
|
|
.Xr device 9 ,
|
|
.Xr printf 9
|
|
.Sh HISTORY
|
|
The
|
|
.Fn BUS_DESCRIBE_INTR
|
|
method and
|
|
.Fn bus_describe_intr
|
|
functions first appeared in
|
|
.Fx 8.1 .
|
|
.Sh BUGS
|
|
It is not currently possible to remove a description from an active interrupt
|
|
handler.
|