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