share/man/man9/pci_intr.9

   1 .\" $NetBSD: pci_intr.9,v 1.12 2003/06/30 12:10:40 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2000 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Bill Sommerfeld
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd May 19, 2002
  31 .Dt PCI_INTR 9
  32 .Os
  33 .Sh NAME
  34 .Nm pci_intr ,
  35 .Nm pci_intr_map ,
  36 .Nm pci_intr_string ,
  37 .Nm pci_intr_establish ,
  38 .Nm pci_intr_disestablish
  39 .Nd PCI bus interrupt manipulation functions
  40 .Sh SYNOPSIS
  41 .In dev/pci/pcivar.h
  42 .Ft int
  43 .Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih"
  44 .Ft const char *
  45 .Fn pci_intr_string "pci_chipset_t *pc" "pci_intr_handle_t ih"
  46 .Ft void *
  47 .Fn pci_intr_establish "pci_chipset_t *pc" "pci_intr_handle_t ih" \
  48 "int ipl" "int (*intrhand)(void *)" "void *intrarg"
  49 .Ft void
  50 .Fn pci_intr_disestablish "pci_chipset_t *pc" "void *ih"
  51 .Sh DESCRIPTION
  52 The
  53 .Nm
  54 functions exist to allow device drivers machine-independent access to
  55 PCI bus interrupts.
  56 The functions described in this page are typically declared in a port's
  57 .Aq Pa machine/pci_machdep.h
  58 header file; however, drivers should generally include
  59 .Aq Pa dev/pci/pcivar.h
  60 to get other PCI-specific declarations as well.
  61 .Pp
  62 Each driver has an
  63 .Fn attach
  64 function which has a bus-specific
  65 .Ft attach_args
  66 structure.
  67 Each driver for a PCI device is passed a pointer to an object of type
  68 .Ft struct pci_attach_args
  69 which contains, among other things, information about the location
  70 of the device in the PCI bus topology sufficient to allow interrupts
  71 from the device to be handled.
  72 .Pp
  73 If a driver wishes to establish an interrupt handler for the device,
  74 it should pass the
  75 .Ft struct pci_attach_args *
  76 to the
  77 .Fn pci_intr_map
  78 function, which returns zero on success, and nonzero on failure.
  79 The function sets the
  80 .Ft pci_intr_handle_t
  81 pointed at by its second argument to a machine-dependent value which
  82 identifies a particular interrupt source.
  83 .Pp
  84 If the driver wishes to refer to the interrupt source in an attach or
  85 error message, it should use the value returned by
  86 .Fn pci_intr_string .
  87 .Pp
  88 Subsequently, when the driver is prepared to receive interrupts, it
  89 should call
  90 .Fn pci_intr_establish
  91 to actually establish the handler; when the device interrupts,
  92 .Fa intrhand
  93 will be called with a single argument
  94 .Fa intrarg ,
  95 and will run at the interrupt priority level
  96 .Fa ipl .
  97 .Pp
  98 The return value of
  99 .Fn pci_intr_establish
 100 may be saved and passed to
 101 .Fn pci_intr_disestablish
 102 to disable the interrupt handler
 103 when the driver is no longer interested in interrupts from the device.
 104 .Ss PORTING
 105 A port's implementation of
 106 .Fn pci_intr_map
 107 may use the following members of
 108 .Ft struct pci_attach_args
 109 to determine how the device's interrupts are routed.
 110 .Bd -literal
 111         pci_chipset_tag_t pa_pc;
 112         pcitag_t pa_tag;
 113         pcitag_t pa_intrtag; /* intr. appears to come from here */
 114         pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */
 115         pci_intr_line_t pa_intrline; /* intr. routing information */
 116         pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */
 117 .Ed
 118 .Pp
 119 PCI-PCI
 120 bridges swizzle (permute) interrupt wiring.
 121 Depending on implementation details, it may be more convenient to use
 122 either original or the swizzled interrupt parameters.
 123 The original device tag and interrupt pin can be found in
 124 .Ft pa_tag
 125 and
 126 .Ft pa_rawintrpin
 127 respectively, while the swizzled tag and pin can be found in
 128 .Ft pa_intrtag
 129 and
 130 .Ft pa_intrpin .
 131 .Pp
 132 When a device is attached to a primary bus, both pairs of fields
 133 contain the same values.
 134 When a device is found behind one or more pci-pci bridges,
 135 .Ft pa_intrpin
 136 contains the
 137 .Dq swizzled
 138 interrupt pin number, while
 139 .Ft pa_rawintrpin
 140 contains the original interrupt pin;
 141 .Ft pa_tag
 142 contains the PCI tag of the device itself, and
 143 .Ft pa_intrtag
 144 contains the PCI tag of the uppermost bridge device.