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