MFC 198085:

Add a manual page for BUS_BIND_INTR() and bus_bind_intr().

share/man/man9/BUS_BIND_INTR.9

@@ -0,0 +1,96 @@
+.\" -*- 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_BIND_INTR 9
+.Os
+.Sh NAME
+.Nm BUS_BIND_INTR ,
+.Nm bus_bind_intr
+.Nd "bind an interrupt resource to a specific CPU"
+.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" "int cpu"
+.Fc
+.Ft int
+.Fn bus_bind_intr "device_t dev" "struct resource *irq" "int cpu"
+.Sh DESCRIPTION
+The
+.Fn BUS_BIND_INTR
+method allows an interrupt resource to be pinned to a specific CPU.
+The interrupt resource must have an interrupt handler attached via
+.Xr BUS_SETUP_INTR 9 .
+The
+.Fa cpu
+parameter corresponds to the ID of a valid CPU in the system.
+Binding an interrupt restricts the
+.Xr cpuset 2
+of any associated interrupt threads to only include the specified CPU.
+It may also direct the low-level interrupt handling of the interrupt to the
+specified CPU as well,
+but this behavior is platform-dependent.
+If the value
+.Dv NOCPU
+is used for
+.Fa cpu ,
+then the interrupt will be
+.Dq unbound
+which restores any associated interrupt threads back to the default cpuset.
+.Pp
+Non-sleepable locks such as mutexes should not be held across calls to these
+functions.
+.Pp
+The
+.Fn bus_bind_intr
+function is a simple wrapper around
+.Fn BUS_BIND_INTR .
+.Pp
+Note that currently there is no attempt made to arbitrate between
+multiple bind requests for the same interrupt from either the same
+device or multiple devices.
+There is also no arbitration between interrupt binding requests submitted
+by userland via
+.Xr cpuset 2
+and
+.Fn BUS_BIND_INTR .
+The most recent binding request is the one that will be in effect.
+.Sh SEE ALSO
+.Xr BUS_SETUP_INTR 9 ,
+.Xr cpuset 2 ,
+.Xr device 9
+.Sh HISTORY
+The
+.Fn BUS_BIND_INTR
+method and
+.Fn bus_bind_intr
+functions first appeared in
+.Fx 7.2 .

share/man/man9/Makefile

@@ -23,6 +23,7 @@ MAN=	accept_filter.9 \
 	bus_activate_resource.9 \
 	BUS_ADD_CHILD.9 \
 	bus_alloc_resource.9 \
+	BUS_BIND_INTR.9 \
 	bus_child_present.9 \
 	BUS_CONFIG_INTR.9 \
 	bus_dma.9 \
@@ -402,6 +403,7 @@ MLINKS+=bpf.9 bpf_filter.9 \
 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_dma.9 busdma.9 \
 	bus_dma.9 bus_dmamap_create.9 \
 	bus_dma.9 bus_dmamap_destroy.9 \