1.\" $NetBSD: pci_intr.9,v 1.4 2001/06/21 11:59:01 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgment: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd December 27, 2000 38.Dt PCI_INTR 9 39.Os 40.Sh NAME 41.Nm pci_intr , 42.Nm pci_intr_map , 43.Nm pci_intr_string , 44.Nm pci_intr_establish , 45.Nm pci_intr_disestablish 46.Nd PCI bus interrupt manipulation functions 47.Sh SYNOPSIS 48.Fd #include <dev/pci/pcivar.h> 49.Ft int 50.Fn pci_intr_map "struct pci_attach_args *pa" "pci_intr_handle_t *ih" 51.Ft const char * 52.Fn pci_intr_string "pci_chipset_t *pc" "pci_intr_handle_t ih" 53.Ft void * 54.Fn pci_intr_establish "pci_chipset_t *pc" "pci_intr_handle_t ih" \ 55"int ipl" "int (*intrhand)(void *)" "void *intrarg" 56.Ft void 57.Fn pci_intr_disestablish "pci_chipset_t *pc" "void *ih" 58.Sh DESCRIPTION 59.Pp 60The 61.Nm 62functions exist to allow device drivers machine-independent access to 63PCI bus interrupts. The functions described in this page are 64typically declared in a port's 65.Pa Aq machine/pci_machdep.h 66header file; however, drivers should generally include 67.Pa Aq dev/pci/pcivar.h 68to get other PCI-specific declarations as well. 69.Pp 70Each driver has an 71.Fn attach 72function which has a bus-specific 73.Ft attach_args 74structure. 75Each driver for a PCI device is is passed a pointer to an object of type 76.Ft struct pci_attach_args 77which contains, among other things, information about the location 78of the device in the PCI bus topology sufficient to allow interrupts 79from the device to be handled. 80.Pp 81If a driver wishes to establish an interrupt handler for the device, 82it should pass the 83.Ft struct pci_attach_args * 84to the 85.Fn pci_intr_map 86function, which returns zero on success, and nonzero on failure. The function 87sets the 88.Ft "pci_intr_handle_t" 89pointed at by its second argument to a machine-dependent value which 90identifies a particular interrupt source. 91.Pp 92If the driver wishes to refer to the interrupt source in an attach or 93error message, it should use the value returned by 94.Fn pci_intr_string . 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