1.\" $OpenBSD: pci_intr_map.9,v 1.13 2013/06/04 19:27:10 schwarze 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: June 4 2013 $ 19.Dt PCI_INTR_MAP 9 20.Os 21.Sh NAME 22.Nm pci_intr_map , 23.Nm pci_intr_map_msi , 24.Nm pci_intr_line , 25.Nm pci_intr_string , 26.Nm pci_intr_establish , 27.Nm pci_intr_disestablish 28.Nd PCI interrupts 29.Sh SYNOPSIS 30.In alpha/pci/pci_machdep.h 31.In i386/pci/pci_machdep.h 32.In powerpc/pci/pci_machdep.h 33.In sgi/pci/pci_machdep.h 34.In machine/pci_machdep.h 35.Ft int 36.Fn pci_intr_map "struct pci_attach_args *paa" "pci_intr_handle_t *ih" 37.Ft int 38.Fn pci_intr_map_msi "struct pci_attach_args *paa" "pci_intr_handle_t *ih" 39.Ft int 40.Fn pci_intr_line "pci_intr_handle_t ih" 41.Ft const char * 42.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih" 43.Ft void * 44.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \ 45"int level" "int (*func)(void *)" "void *arg" "const char *name" 46.Ft void 47.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *v" 48.Sh DESCRIPTION 49These functions are provided by the machine-dependent implementation 50for attaching handler functions to the interrupts of PCI devices. 51.Pp 52An architect type is provided by the machine-dependent 53code 54.Va pci_intr_handle_t , 55to be initialised by 56.Fn pci_intr_map 57or 58.Fn pci_intr_map_msi . 59.Pp 60The 61.Fn pci_intr_map 62function should be called first to establish a mapping between a PCI 63pin and the interrupt controller's interrupt vector. 64This process may include resolving the mapping through 65firmware-provided information. 66For devices that support Message Signaled Interrupts (MSI) the 67.Fn pci_intr_map_msi 68function should be called instead. 69This function can fail if the 70system does not support MSI. 71In that case 72.Fn pci_intr_map 73should be called to fall back on classic PCI interrupts. 74.Pp 75Having initialised the 76.Va pci_intr_handle_t 77in the previous step, an interrupt handler can be established using 78.Fn pci_intr_establish 79or converted into printable form using 80.Fn pci_intr_string . 81A handler established using 82.Fn pci_intr_establish 83is always called with the system interrupt priority level set equal to, 84or higher than, 85.Va level . 86.Pp 87.Fn pci_intr_line 88provides the interrupt line extracted from the MD interrupt handle. 89Upon device detachment, 90.Fn pci_intr_disestablish 91should be used to disassociate the handler from the interrupt. 92.Pp 93See 94.Xr spl 9 95for an explanation of the 96.Va ipl 97.Dq interrupt priority levels . 98.Sh EXAMPLES 99A typical code sequence for establishing a handler 100for a device interrupt in the driver might be: 101.Bd -literal -offset 3n 102int 103xxxattach(struct device *parent, struct device *self, void *aux) 104{ 105 struct xxx_softc *sc = (struct xxx_softc *)self; 106 struct pci_attach_args *pa = aux; 107 pci_intr_handle_t ih; 108 const char *intrstr; 109 bus_size_t size; 110 111 \&... 112 113 if (pci_intr_map_msi(pa, &ih) && pci_intr_map(pa, &ih)) { 114 printf(": can't map interrupt\en"); 115 bus_space_unmap(sc->iot, sc->ioh, size); 116 return; 117 } 118 intrstr = pci_intr_string(pa->pa_pc, ih); 119 sc->sc_ih = pci_intr_establish(pa->pa_pc, ih, IPL_NET, 120 xxx_intr, sc, sc->sc_dev.dv_xname); 121 if (!sc->sc_ih) { 122 printf(": can't establish interrupt"); 123 if (intrstr) 124 printf(" at %s", intrstr); 125 printf("\en"); 126 bus_space_unmap(sc->iot, sc->ioh, size); 127 return; 128 } 129 130 printf(": %s\en", intrstr); 131 132 \&... 133} 134.Ed 135.Sh SEE ALSO 136.Xr cardbus 4 , 137.Xr pci 4 , 138.Xr pcibios 4 , 139.Xr pci_conf_read 9 , 140.Xr spl 9 141.Sh HISTORY 142These functions first appeared in 143.Ox 1.2 . 144.\" .Sh AUTHORS 145