pci_intr* page

2 files changed, 125 insertions, 4 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 3beb5477fd3..373c5366c23 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.107 2005/11/14 16:42:42 mickey Exp $
+#	$OpenBSD: Makefile,v 1.108 2005/11/15 11:41:26 mickey Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -17,7 +17,7 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 buffercache.9 bus_dma.9 bus_space.9 \
 	kern.9 knote.9 kthread.9 ktrace.9 loadfirmware.9 lock.9 log.9 \
 	malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 \
 	mountroothook_establish.9 mutex.9 namei.9 \
-	panic.9 pci_conf_read.9 pfind.9 physio.9 pmap.9 \
+	panic.9 pci_conf_read.9 pci_intr_map.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 \
 	shutdownhook_establish.9 sleep.9 spl.9 startuphook_establish.9 \
@@ -213,8 +213,11 @@ MLINKS+=rssadapt.9 ieee80211_rssadapt_choose.9 \
 	rssadapt.9 ieee80211_rssadapt_lower_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_raise_rate.9 \
 	rssadapt.9 ieee80211_rssadapt_updatestats.9
-MLINKS+=pci_conf_read.9 pci_conf_write.9 pci_conf_read.9 pci_make_tag.9
-MLINKS+=pci_conf_read.9 pci_decompose_tag.9
+MLINKS+=pci_conf_read.9 pci_conf_write.9 pci_conf_read.9 pci_make_tag.9 \
+	pci_conf_read.9 pci_decompose_tag.9
+MLINKS+=pci_intr_map.9 pci_intr_string.9 pci_intr_map.9 pci_intr_line.9 \
+	pci_intr_map.9 pci_intr_establish.9 \
+	pci_intr_map.9 pci_intr_disestablish.9
 MLINKS+=pfind.9 pgfind.9
 MLINKS+=pmap.9 pmap_init.9 pmap.9 pmap_enter.9 pmap.9 pmap_remove.9 \
 	pmap.9 pmap_unwire.9 pmap.9 pmap_protect.9 pmap.9 pmap_page_protect.9 \
diff --git a/share/man/man9/pci_intr_map.9 b/share/man/man9/pci_intr_map.9
new file mode 100644
index 00000000000..933a28087ae
--- /dev/null
+++ b/share/man/man9/pci_intr_map.9
@@ -0,0 +1,118 @@
+.\"	$OpenBSD: pci_intr_map.9,v 1.1 2005/11/15 11:41:26 mickey Exp $
+.\"
+.\" Copyright (c) 2005 Michael Shalayeff
+.\" All rights reserved.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd November 20, 2005
+.Dt pci_intr_map 9
+.Os
+.Sh NAME
+.Nm pci_intr_map ,
+.Nm pci_intr_string ,
+.Nm pci_intr_establish ,
+.Nm pci_intr_disestablish
+.Nd PCI interrupts
+.Sh SYNOPSIS
+.Fd #include <alpha/pci/pci_machdep.h>
+.Fd #include <i386/pci/pci_machdep.h>
+.Fd #include <cats/pci/pci_machdep.h>
+.Fd #include <powerpc/pci/pci_machdep.h>
+.Fd #include <sgi/pci/pci_machdep.h>
+.Fd #include <machine/pci_machdep.h>
+.Ft int
+.Fn pci_intr_map "struct pci_attach_args *paa" "pci_intr_handle_t *ih"
+.Ft int
+.Fn pci_intr_line "pci_intr_handle_t *ih"
+.Ft const char *
+.Fn pci_intr_string "pci_chipset_tag_t pc" "pci_intr_handle_t ih"
+.Ft void *
+.Fn pci_intr_establish "pci_chipset_tag_t pc" "pci_intr_handle_t ih" \
+"int type" "int (*func)(void *)" "void *arg" "char *name"
+.Ft void
+.Fn pci_intr_disestablish "pci_chipset_tag_t pc" "void *v"
+.Sh DESCRIPTION
+These functions are provided by the machine-dependant implementaion
+for attaching handler function to PCI devices' interrupts.
+.Pp
+An architected type is provided by the machine-dependant
+code
+.Nm pci_intr_handle_t
+to be initialied by the
+.Nm pci_intr_map .
+.Pp
+The
+.Nm pci_intr_map
+function shall be called first to establish a mapping between a PCI
+pin and the interrupt controller's interrupt vector.
+This process may include resolving the mapping through the means
+of firmware-provided information.
+Having the
+.Nm pci_intr_handle_t
+initialised in the previous step an interrupt handler can be established using
+.Nm pci_intr_establish
+or converted into printable form using
+.Nm pci_intr_string .
+The
+.Nm pci_intr_line
+provides the interrupt line extracted form the MD interrupt handle.
+Upon device detachment one shall use
+.Nm pci_intr_disestablish
+to disassociate the handler from the interrupt.
+.Pp
+A typical code sequence for establishing a handler
+for a device interrupt in the driver might be:
+.Bd -literal
+int
+xxxattach(struct device *parent, struct device *self, void *aux)
+{
+	struct xxx_softc *sc = (struct xxx_softc *)self;
+	struct pci_attach_args *pa = aux;
+	pci_intr_handle_t ih;
+	const char *intrstr;
+	bus_size_t size;  
+
+	\&...
+
+	if (pci_intr_map(pa, &ih)) {
+		printf(": can't map interrupt\\n");
+		bus_space_unmap(sc->iot, sc->ioh, size);
+		return;
+	}
+	intrstr = pci_intr_string(pa->pa_pc, ih);
+	sc->sc_ih = pci_intr_establish(pa->pa_pc, ih, IPL_NET,
+	    xxx_intr, sc, sc->sc_dev.dv_xname);
+	if (!sc->sc_ih) {
+		printf(": can't establish interrupt");
+		if (intrstr)
+			printf(" at %s", intrstr);
+		printf("\\n");
+		bus_space_unmap(sc->iot, sc->ioh, size);
+		return;
+	}
+
+	printf(": %s\\n", intrstr);
+
+	\&...
+}
+.Ed
+.Sh SEE ALSO
+.Xr cardbus 4 ,
+.Xr pci 4 ,
+.Xr pcibios 4 ,
+.Xr pci_conf_read 9 .
+.Sh HISTORY
+These functions first appeared in
+.Ox 1.2 .
+.\" .Sh AUTHORS