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