share/man/man9/BUS_BIND_INTR.9

   1 .\" -*- nroff -*-
   2 .\"
   3 .\" Copyright (c) 2009 Advanced Computing Technologies LLC
   4 .\" Written by: John H. Baldwin <jhb@FreeBSD.org>
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd October 14, 2009
  31 .Dt BUS_BIND_INTR 9
  32 .Os
  33 .Sh NAME
  34 .Nm BUS_BIND_INTR ,
  35 .Nm bus_bind_intr
  36 .Nd "bind an interrupt resource to a specific CPU"
  37 .Sh SYNOPSIS
  38 .In sys/param.h
  39 .In sys/bus.h
  40 .Ft int
  41 .Fo BUS_BIND_INTR
  42 .Fa "device_t dev" "device_t child" "struct resource *irq" "int cpu"
  43 .Fc
  44 .Ft int
  45 .Fn bus_bind_intr "device_t dev" "struct resource *irq" "int cpu"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn BUS_BIND_INTR
  49 method allows an interrupt resource to be pinned to a specific CPU.
  50 The interrupt resource must have an interrupt handler attached via
  51 .Xr BUS_SETUP_INTR 9 .
  52 The
  53 .Fa cpu
  54 parameter corresponds to the ID of a valid CPU in the system.
  55 Binding an interrupt restricts the
  56 .Xr cpuset 2
  57 of any associated interrupt threads to only include the specified CPU.
  58 It may also direct the low-level interrupt handling of the interrupt to the
  59 specified CPU as well,
  60 but this behavior is platform-dependent.
  61 If the value
  62 .Dv NOCPU
  63 is used for
  64 .Fa cpu ,
  65 then the interrupt will be
  66 .Dq unbound
  67 which restores any associated interrupt threads back to the default cpuset.
  68 .Pp
  69 Non-sleepable locks such as mutexes should not be held across calls to these
  70 functions.
  71 .Pp
  72 The
  73 .Fn bus_bind_intr
  74 function is a simple wrapper around
  75 .Fn BUS_BIND_INTR .
  76 .Pp
  77 Note that currently there is no attempt made to arbitrate between
  78 multiple bind requests for the same interrupt from either the same
  79 device or multiple devices.
  80 There is also no arbitration between interrupt binding requests submitted
  81 by userland via
  82 .Xr cpuset 2
  83 and
  84 .Fn BUS_BIND_INTR .
  85 The most recent binding request is the one that will be in effect.
  86 .Sh RETURN VALUES
  87 Zero is returned on success, otherwise an appropriate error is returned.
  88 .Sh SEE ALSO
  89 .Xr BUS_SETUP_INTR 9 ,
  90 .Xr cpuset 2 ,
  91 .Xr device 9
  92 .Sh HISTORY
  93 The
  94 .Fn BUS_BIND_INTR
  95 method and
  96 .Fn bus_bind_intr
  97 functions first appeared in
  98 .Fx 7.2 .