1.\" $OpenBSD: pci_intr_map.9,v 1.8 2007/08/02 07:13:27 jmc Exp $ 2.\" 3.\" Copyright (c) 2005 Michael Shalayeff 4.\" All rights reserved. 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: August 2 2007 $ 19.Dt PCI_INTR_MAP 9 20.Os 21.Sh NAME 22.Nm pci_intr_map , 23.Nm pci_intr_line , 24.Nm pci_intr_string , 25.Nm pci_intr_establish , 26.Nm pci_intr_disestablish 27.Nd PCI interrupts 28.Sh SYNOPSIS 29.Fd #include <alpha/pci/pci_machdep.h> 30.Fd #include <i386/pci/pci_machdep.h> 31.Fd #include <powerpc/pci/pci_machdep.h> 32.Fd #include <sgi/pci/pci_machdep.h> 33.Fd #include <machine/pci_machdep.h> 34.Ft int 35.Fn pci_intr_map "struct pci_attach_args *paa" "pci_intr_handle_t *ih" 36.Ft int 37.Fn pci_intr_line "pci_intr_handle_t ih" 38.Ft const char * 39.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 40.Ft void * 41.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 42"int level" "int (*func)(void *)" "void *arg" "char *name" 43.Ft void 44.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *v" 45.Sh DESCRIPTION 46These functions are provided by the machine-dependent implementation 47for attaching handler functions to the interrupts of PCI devices. 48.Pp 49An architect type is provided by the machine-dependent 50code 51.Va pci_intr_handle_t , 52to be initialised by 53.Fn pci_intr_map . 54.Pp 55The 56.Fn pci_intr_map 57function should be called first to establish a mapping between a PCI 58pin and the interrupt controller's interrupt vector. 59This process may include resolving the mapping through 60firmware-provided information. 61.Pp 62Having initialised the 63.Va pci_intr_handle_t 64in the previous step, an interrupt handler can be established using 65.Fn pci_intr_establish 66or converted into printable form using 67.Fn pci_intr_string . 68A handler established using 69.Fn pci_intr_establish 70is always called with the system interrupt priority level set equal to, 71or higher than, 72.Va level . 73.Pp 74.Fn pci_intr_line 75provides the interrupt line extracted from the MD interrupt handle. 76Upon device detachment, 77.Fn pci_intr_disestablish 78should be used to disassociate the handler from the interrupt. 79.Pp 80See 81.Xr spl 9 82for an explanation of the 83.Va ipl 84.Dq interrupt priority levels. 85.Sh EXAMPLES 86A typical code sequence for establishing a handler 87for a device interrupt in the driver might be: 88.Bd -literal -offset 3n 89int 90xxxattach(struct device *parent, struct device *self, void *aux) 91{ 92 struct xxx_softc *sc = (struct xxx_softc *)self; 93 struct pci_attach_args *pa = aux; 94 pci_intr_handle_t ih; 95 const char *intrstr; 96 bus_size_t size; 97 98 \&... 99 100 if (pci_intr_map(pa, &ih)) { 101 printf(": can't map interrupt\\n"); 102 bus_space_unmap(sc->iot, sc->ioh, size); 103 return; 104 } 105 intrstr = pci_intr_string(pa->pa_pc, ih); 106 sc->sc_ih = pci_intr_establish(pa->pa_pc, ih, IPL_NET, 107 xxx_intr, sc, sc->sc_dev.dv_xname); 108 if (!sc->sc_ih) { 109 printf(": can't establish interrupt"); 110 if (intrstr) 111 printf(" at %s", intrstr); 112 printf("\\n"); 113 bus_space_unmap(sc->iot, sc->ioh, size); 114 return; 115 } 116 117 printf(": %s\\n", intrstr); 118 119 \&... 120} 121.Ed 122.Sh SEE ALSO 123.Xr cardbus 4 , 124.Xr pci 4 , 125.Xr pcibios 4 , 126.Xr pci_conf_read 9 , 127.Xr spl 9 128.Sh HISTORY 129These functions first appeared in 130.Ox 1.2 . 131.\" .Sh AUTHORS 132