1.\" $NetBSD: pci_intr.9,v 1.23 2015/10/13 09:21:56 msaitoh 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 October 13, 2015 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_evcnt , 38.Nm pci_intr_establish , 39.Nm pci_intr_disestablish , 40.Nm pci_intr_setattr 41.Nd PCI bus interrupt manipulation functions 42.Sh SYNOPSIS 43.In dev/pci/pcivar.h 44.Ft int 45.Fn pci_intr_map "const struct pci_attach_args *pa" "pci_intr_handle_t *ih" 46.Ft const char * 47.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" "char *buf" "size_t len" 48.Ft const struct evcnt * 49.Fn pci_intr_evcnt "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 50.Ft void * 51.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 52"int ipl" "int (*intrhand)(void *)" "void *intrarg" 53.Ft void 54.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *ih" 55.Ft int 56.Fn pci_intr_setattr "pci_chipset_tag_t pc" "pci_intr_handle_t *ih" "int attr" "uint64_t data" 57.Sh DESCRIPTION 58The 59.Nm 60functions exist to allow device drivers machine-independent access to 61PCI bus interrupts. 62The functions described in this page are typically declared in a port's 63.In machine/pci_machdep.h 64header file; however, drivers should generally include 65.In dev/pci/pcivar.h 66to get other PCI-specific declarations as well. 67.Pp 68Each driver has an 69.Fn attach 70function which has a bus-specific 71.Ft attach_args 72structure. 73Each driver for a PCI device is passed a pointer to an object of type 74.Ft struct pci_attach_args 75which contains, among other things, information about the location 76of the device in the PCI bus topology sufficient to allow interrupts 77from the device to be handled. 78.Pp 79If a driver wishes to establish an interrupt handler for the device, 80it should pass the 81.Ft struct pci_attach_args * 82to the 83.Fn pci_intr_map 84function, which returns zero on success, and nonzero on failure. 85The function sets the 86.Ft pci_intr_handle_t 87pointed at by its second argument to a machine-dependent value which 88identifies a particular interrupt source. 89.Pp 90If the driver wishes to refer to the interrupt source in an attach or 91error message, it should use the value returned by 92.Fn pci_intr_string . 93The buffer passed to 94.Fn pci_intr_string 95should be at least 96.Dv PCI_INTRSTR_LEN 97bytes. 98.Pp 99Subsequently, when the driver is prepared to receive interrupts, it 100should call 101.Fn pci_intr_establish 102to actually establish the handler; when the device interrupts, 103.Fa intrhand 104will be called with a single argument 105.Fa intrarg , 106and will run at the interrupt priority level 107.Fa ipl . 108.Pp 109The return value of 110.Fn pci_intr_establish 111may be saved and passed to 112.Fn pci_intr_disestablish 113to disable the interrupt handler 114when the driver is no longer interested in interrupts from the device. 115.Pp 116The 117.Fn pci_intr_setattr 118function sets an attribute 119.Fa attr 120of the interrupt handler to 121.Fa data . 122Currenty, only the following attribute is supported: 123.Bl -tag -width PCI_INTR_MPSAFE 124.It Dv PCI_INTR_MPSAFE 125If this attribute is set to 126.Dv true , 127it specifies that the interrupt handler is multiprocessor safe and works its 128own locking; otherwise the kernel lock will be held for the call to the 129interrupt handler. 130The default is 131.Dv false . 132.El 133.Pp 134The 135.Fn pci_intr_setattr 136function returns zero on success, and nonzero on failure. 137.Pp 138The 139.Fn pci_intr_evcnt 140function should return an evcnt structure pointer or 141.Dv NULL 142if there is no evcnt associated with this interrupt. 143See 144.Xr evcnt 9 145for more details. 146.Ss PORTING 147A port's implementation of 148.Fn pci_intr_map 149may use the following members of 150.Ft struct pci_attach_args 151to determine how the device's interrupts are routed. 152.Bd -literal 153 pci_chipset_tag_t pa_pc; 154 pcitag_t pa_tag; 155 pcitag_t pa_intrtag; /* intr. appears to come from here */ 156 pci_intr_pin_t pa_intrpin; /* intr. appears on this pin */ 157 pci_intr_line_t pa_intrline; /* intr. routing information */ 158 pci_intr_pin_t pa_rawintrpin; /* unswizzled pin */ 159.Ed 160.Pp 161PCI-PCI 162bridges swizzle (permute) interrupt wiring. 163Depending on implementation details, it may be more convenient to use 164either original or the swizzled interrupt parameters. 165The original device tag and interrupt pin can be found in 166.Ft pa_tag 167and 168.Ft pa_rawintrpin 169respectively, while the swizzled tag and pin can be found in 170.Ft pa_intrtag 171and 172.Ft pa_intrpin . 173.Pp 174When a device is attached to a primary bus, both pairs of fields 175contain the same values. 176When a device is found behind one or more pci-pci bridges, 177.Ft pa_intrpin 178contains the 179.Dq swizzled 180interrupt pin number, while 181.Ft pa_rawintrpin 182contains the original interrupt pin; 183.Ft pa_tag 184contains the PCI tag of the device itself, and 185.Ft pa_intrtag 186contains the PCI tag of the uppermost bridge device. 187.Sh SEE ALSO 188.Xr evcnt 9 , 189.Xr pci 9 190