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