1.\" $NetBSD: pci_intr.9,v 1.14 2010/03/22 18:58:33 joerg 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 52The 53.Nm 54functions exist to allow device drivers machine-independent access to 55PCI bus interrupts. 56The functions described in this page are typically declared in a port's 57.In machine/pci_machdep.h 58header file; however, drivers should generally include 59.In dev/pci/pcivar.h 60to get other PCI-specific declarations as well. 61.Pp 62Each driver has an 63.Fn attach 64function which has a bus-specific 65.Ft attach_args 66structure. 67Each driver for a PCI device is passed a pointer to an object of type 68.Ft struct pci_attach_args 69which contains, among other things, information about the location 70of the device in the PCI bus topology sufficient to allow interrupts 71from the device to be handled. 72.Pp 73If a driver wishes to establish an interrupt handler for the device, 74it should pass the 75.Ft struct pci_attach_args * 76to the 77.Fn pci_intr_map 78function, which returns zero on success, and nonzero on failure. 79The function sets the 80.Ft pci_intr_handle_t 81pointed at by its second argument to a machine-dependent value which 82identifies a particular interrupt source. 83.Pp 84If the driver wishes to refer to the interrupt source in an attach or 85error message, it should use the value returned by 86.Fn pci_intr_string . 87.Pp 88Subsequently, when the driver is prepared to receive interrupts, it 89should call 90.Fn pci_intr_establish 91to actually establish the handler; when the device interrupts, 92.Fa intrhand 93will be called with a single argument 94.Fa intrarg , 95and will run at the interrupt priority level 96.Fa ipl . 97.Pp 98The return value of 99.Fn pci_intr_establish 100may be saved and passed to 101.Fn pci_intr_disestablish 102to disable the interrupt handler 103when the driver is no longer interested in interrupts from the device. 104.Ss PORTING 105A port's implementation of 106.Fn pci_intr_map 107may use the following members of 108.Ft struct pci_attach_args 109to 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 119PCI-PCI 120bridges swizzle (permute) interrupt wiring. 121Depending on implementation details, it may be more convenient to use 122either original or the swizzled interrupt parameters. 123The original device tag and interrupt pin can be found in 124.Ft pa_tag 125and 126.Ft pa_rawintrpin 127respectively, while the swizzled tag and pin can be found in 128.Ft pa_intrtag 129and 130.Ft pa_intrpin . 131.Pp 132When a device is attached to a primary bus, both pairs of fields 133contain the same values. 134When a device is found behind one or more pci-pci bridges, 135.Ft pa_intrpin 136contains the 137.Dq swizzled 138interrupt pin number, while 139.Ft pa_rawintrpin 140contains the original interrupt pin; 141.Ft pa_tag 142contains the PCI tag of the device itself, and 143.Ft pa_intrtag 144contains the PCI tag of the uppermost bridge device. 145