1.\" $NetBSD: pci_intr.9,v 1.17 2014/03/30 23:28:14 christos 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 March 30, 2014 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 "const 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" "char *buf" "size_t len" 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 . 87The buffer passed to 88.Fn pci_intr_string 89should be at least 90.Dv PCI_INTRSTR_LEN 91bytes. 92.Pp 93Subsequently, when the driver is prepared to receive interrupts, it 94should call 95.Fn pci_intr_establish 96to actually establish the handler; when the device interrupts, 97.Fa intrhand 98will be called with a single argument 99.Fa intrarg , 100and will run at the interrupt priority level 101.Fa ipl . 102.Pp 103The return value of 104.Fn pci_intr_establish 105may be saved and passed to 106.Fn pci_intr_disestablish 107to disable the interrupt handler 108when the driver is no longer interested in interrupts from the device. 109.Ss PORTING 110A port's implementation of 111.Fn pci_intr_map 112may use the following members of 113.Ft struct pci_attach_args 114to determine how the device's interrupts are routed. 115.Bd -literal 116 pci_chipset_tag_t pa_pc; 117 pcitag_t pa_tag; 118 pcitag_t pa_intrtag; /* intr. appears to come from here */ 119 pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */ 120 pci_intr_line_t pa_intrline; /* intr. routing information */ 121 pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */ 122.Ed 123.Pp 124PCI-PCI 125bridges swizzle (permute) interrupt wiring. 126Depending on implementation details, it may be more convenient to use 127either original or the swizzled interrupt parameters. 128The original device tag and interrupt pin can be found in 129.Ft pa_tag 130and 131.Ft pa_rawintrpin 132respectively, while the swizzled tag and pin can be found in 133.Ft pa_intrtag 134and 135.Ft pa_intrpin . 136.Pp 137When a device is attached to a primary bus, both pairs of fields 138contain the same values. 139When a device is found behind one or more pci-pci bridges, 140.Ft pa_intrpin 141contains the 142.Dq swizzled 143interrupt pin number, while 144.Ft pa_rawintrpin 145contains the original interrupt pin; 146.Ft pa_tag 147contains the PCI tag of the device itself, and 148.Ft pa_intrtag 149contains the PCI tag of the uppermost bridge device. 150