manpage for the bits of intrmap we're using at the moment.

2 files changed, 128 insertions, 2 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 0906dd1130e..d6def750b7a 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.301 2020/06/16 05:17:09 dlg Exp $
+#	$OpenBSD: Makefile,v 1.302 2020/06/17 00:28:28 dlg Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -20,7 +20,8 @@ MAN=	aml_evalnode.9 atomic_add_int.9 atomic_cas_uint.9 \
 	ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
 	ieee80211_radiotap.9 if_addrhook_add.9 if_get.9 if_rxr_init.9 \
 	ifiq_input.9 ifq_enqueue.9 \
-	ifq_deq_begin.9 imax.9 iic.9 intro.9 inittodr.9 intr_barrier.9 \
+	ifq_deq_begin.9 imax.9 iic.9 intro.9 inittodr.9 \
+	intr_barrier.9 intrmap_create.9 \
 	KASSERT.9 km_alloc.9 knote.9 kthread.9 ktrace.9 \
 	lim_cur.9 loadfirmware.9 log.9 \
 	malloc.9 membar_sync.9 memcmp.9 mbuf.9 mbuf_tags.9 md5.9 mi_switch.9 \
diff --git a/share/man/man9/intrmap_create.9 b/share/man/man9/intrmap_create.9
new file mode 100644
index 00000000000..33f1985d180
--- /dev/null
+++ b/share/man/man9/intrmap_create.9
@@ -0,0 +1,125 @@
+.\" $OpenBSD: intrmap_create.9,v 1.1 2020/06/17 00:28:28 dlg Exp $
+.\"
+.\" Copyright (c) 2020 David Gwynne <dlg@openbsd.org>
+.\"
+.\" 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 $Mdocdate: June 17 2020 $
+.Dt INTRMAP_CREATE 9
+.Os
+.Sh NAME
+.Nm intrmap_create ,
+.Nm intrmap_destroy ,
+.Nm intrmap_count ,
+.Nm intrmap_cpu
+.Nd interrupt to CPU mapping API
+.Sh SYNOPSIS
+.In sys/inrtmap.h
+.Ft struct intrmap *
+.Fo intrmap_create
+.Fa "const struct device *dv"
+.Fa "unsigned int nintr"
+.Fa "unsigned int maxintr"
+.Fa "unsigned int flags"
+.Fc
+.Ft void
+.Fn intrmap_destroy "struct intrmap *im"
+.Ft unsigned int
+.Fn intrmap_count "struct intrmap *im"
+.Ft unsigned int
+.Fn intrmap_cpu "struct intrmap *im" "unsigned int index"
+.Sh DESCRIPTION
+The interrupt to CPU mapping API supports the use of multiple CPUs
+by hardware drivers.
+Drivers that can use multiple interrupts use the API to request a
+set of CPUs that they can establish those interrupts on.
+The API limits the requested number of interrupts to what is available
+on the system, and attempts to distribute the requested interrupts
+over those CPUs.
+On some platforms the API will filter the set of available CPUs.
+.\" to avoid hyperthreads, basically.
+.Pp
+.Fn intrmap_create
+allocates an interrupt map data structure for use by the driver
+identified by
+.Fa dv .
+The number of interrupts the hardware supports is specified via the
+.Fa nintr
+argument.
+The driver supplies the maximum number of interrupts it can support
+via
+.Fa maxintr ,
+which, along with the number of available CPUs at the time the
+function is called, is used as a constraint on the number of requested
+interrupts.
+.Fa nintr
+may be zero to use the driver limit as the number of requested
+interrupts.
+The
+.Fa flags
+argument may have the following defines OR'ed together:
+.Bl -tag -width xxx -offset indent
+.It Dv INTRMAP_POWEROF2
+The hardware only supports a power of 2 number of interrupts, so
+constrain the number of supplied interrupts after the system and
+driver limits are applied.
+.El
+.Pp
+.Fn intrmap_destroy
+frees the memory associated with the interrupt map data structure
+passed via
+.Fa im .
+.Pp
+.Fn intrmap_count
+returns the number of interrupts that the driver can establish
+according to the
+.Fa im
+interrupt map.
+.Pp
+.Fn intrmap_cpu
+returns which CPU the interrupt specified in
+.Fa index
+should be established on according to the
+.Fa im
+interrupt map.
+Interrupts are identified as a number from 0 to the value returned by
+.Fn intrmap_count .
+.Sh CONTEXT
+.Fn intrmap_create ,
+.Fn intrmap_destroy ,
+.Fn intrmap_count ,
+and
+.Fn intrmap_cpu
+can be called during autoconf, or from process context.
+.Sh RETURN VALUES
+.Fn intrmap_create
+returns a pointer to a interrupt mapping structure on success, or
+.Dv NULL
+on failure.
+.Pp
+.Fn intrmap_count
+returns the number of interrupts that were allocated for the driver
+to use.
+.Pp
+.Fn intrmap_cpu
+returns an identifier for the CPU that the interrupt should be
+established on.
+.\" .Sh SEE ALSO
+.\" .Xr pci_intr_establish_cpuid 9
+.Sh HISTORY
+The interrupt mapping API is based on the if_ringmap API in
+.Dx .
+It was ported to
+.Ox 6.8
+by
+.An David Gwynne Aq Mt dlg@openbsd.org .