Tue Jul 21 03:12:50 2015 UTC ()
add pci_intr_alloc() man


(knakahara)
diff -r1.1970 -r1.1971 src/distrib/sets/lists/comp/mi
diff -r1.388 -r1.389 src/share/man/man9/Makefile
diff -r1.3 -r1.4 src/share/man/man9/pci_msi.9
cvs diff -r1.1970 -r1.1971 src/distrib/sets/lists/comp/mi (expand / switch to context diff)
--- src/distrib/sets/lists/comp/mi 2015/07/12 08:11:27 1.1970
+++ src/distrib/sets/lists/comp/mi 2015/07/21 03:12:50 1.1971
@@ -1,4 +1,4 @@
-#	$NetBSD: mi,v 1.1970 2015/07/12 08:11:27 hannken Exp $
+#	$NetBSD: mi,v 1.1971 2015/07/21 03:12:50 knakahara Exp $
 #
 # Note: don't delete entries from here - mark them as "obsolete" instead.
 #
@@ -10618,12 +10618,15 @@
 ./usr/share/man/cat9/pci_get_capability.0	comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_get_powerstate.0	comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr.0			comp-sys-catman		.cat
+./usr/share/man/cat9/pci_intr_alloc.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_disestablish.0	comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_distribute.0	comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_establish.0	comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_evcnt.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_map.0		comp-sys-catman		.cat
+./usr/share/man/cat9/pci_intr_release.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intr_string.0		comp-sys-catman		.cat
+./usr/share/man/cat9/pci_intr_type.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intx_alloc.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_intx_release.0		comp-sys-catman		.cat
 ./usr/share/man/cat9/pci_make_tag.0		comp-sys-catman		.cat
@@ -17422,12 +17425,15 @@
 ./usr/share/man/html9/pci_get_capability.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_get_powerstate.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr.html		comp-sys-htmlman	html
+./usr/share/man/html9/pci_intr_alloc.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_disestablish.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_distribute.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_establish.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_evcnt.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_map.html		comp-sys-htmlman	html
+./usr/share/man/html9/pci_intr_release.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intr_string.html	comp-sys-htmlman	html
+./usr/share/man/html9/pci_intr_type.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intx_alloc.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_intx_release.html	comp-sys-htmlman	html
 ./usr/share/man/html9/pci_make_tag.html		comp-sys-htmlman	html
@@ -24391,12 +24397,15 @@
 ./usr/share/man/man9/pci_get_capability.9	comp-sys-man		.man
 ./usr/share/man/man9/pci_get_powerstate.9	comp-sys-man		.man
 ./usr/share/man/man9/pci_intr.9			comp-sys-man		.man
+./usr/share/man/man9/pci_intr_alloc.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_disestablish.9	comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_distribute.9	comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_establish.9	comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_evcnt.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_map.9		comp-sys-man		.man
+./usr/share/man/man9/pci_intr_release.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_intr_string.9		comp-sys-man		.man
+./usr/share/man/man9/pci_intr_type.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_intx_alloc.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_intx_release.9		comp-sys-man		.man
 ./usr/share/man/man9/pci_make_tag.9		comp-sys-man		.man
cvs diff -r1.388 -r1.389 src/share/man/man9/Makefile (expand / switch to context diff)
--- src/share/man/man9/Makefile 2015/07/12 08:11:27 1.388
+++ src/share/man/man9/Makefile 2015/07/21 03:12:50 1.389
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.388 2015/07/12 08:11:27 hannken Exp $
+#       $NetBSD: Makefile,v 1.389 2015/07/21 03:12:50 knakahara Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -578,6 +578,9 @@
 	pci.9 PCI_PRODUCT.9 \
 	pci.9 PCI_REVISION.9
 MLINKS+=pci_msi.9 pci_msix.9 \
+	pci_msi.9 pci_intr_alloc.9 \
+	pci_msi.9 pci_intr_release.9 \
+	pci_msi.9 pci_intr_type.9 \
 	pci_msi.9 pci_intx_alloc.9 \
 	pci_msi.9 pci_intx_release.9 \
 	pci_msi.9 pci_msi_count.9 \
cvs diff -r1.3 -r1.4 src/share/man/man9/pci_msi.9 (expand / switch to context diff)
--- src/share/man/man9/pci_msi.9 2015/05/15 08:39:14 1.3
+++ src/share/man/man9/pci_msi.9 2015/07/21 03:12:50 1.4
@@ -1,4 +1,4 @@
-.\" $NetBSD: pci_msi.9,v 1.3 2015/05/15 08:39:14 knakahara Exp $
+.\" $NetBSD: pci_msi.9,v 1.4 2015/07/21 03:12:50 knakahara Exp $
 .\"
 .\" Copyright (c) 2015 Internet Initiative Japan Inc.
 .\" All rights reserved.
@@ -24,7 +24,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd May 11, 2015
+.Dd Jul 15, 2015
 .Dt PCI_MSI 9
 .Os
 .Sh NAME
@@ -38,7 +38,9 @@
 .Nm pci_msix_alloc_exact ,
 .Nm pci_msix_alloc_map ,
 .Nm pci_intx_alloc ,
-.Nm pci_intr_release
+.Nm pci_intr_alloc ,
+.Nm pci_intr_release,
+.Nm pci_intr_type
 .Nd PCI MSI{,-X} manipulation functions
 .Sh SYNOPSIS
 .Ft int
@@ -63,9 +65,15 @@
 .Ft int
 .Fn pci_intx_alloc  "struct pci_attach_args *pa" \
 "pci_intr_handle_t **ihp"
+.Ft int
+.Fn pci_intr_alloc  "struct pci_attach_args *pa" \
+"pci_intr_handle_t **ihp" "int *counts" \
+"pci_intr_type_t max_type"
 .Ft void
 .Fn pci_intr_release "pci_chipset_tag_t pc" \
 "pci_intr_handle_t *pih" "int count"
+.Ft pci_intr_type_t
+.Fn pci_intr_type "pci_intr_handle_t ih"
 .Sh DESCRIPTION
 The
 .Nm
@@ -185,5 +193,111 @@
 and
 .Fn pci_msix_alloc
 have (the functions allocate memory for interrupt handlers).
+.Pp
+.Fn pci_intr_alloc
+is wrapper function which select and automatically fallback
+allocation functions according to the argument
+.Fa counts .
+The elements of
+.Fa counts
+array means each required interrupt count for INTx, MSI, and MSI-X.
+The index count of
+.Fa counts
+must be
+.Dv PCI_INTR_TYPE_SIZE .
+.Fa max_type
+must be PCI_INTR_TYPE_MSIX, PCI_INTR_TYPE_MSI, or PCI_INTR_TYPE_INTX.
+The parameter does not mean array index counts of
+.Fa counts .
+The parameter means the interrupt type which
+.Fn pci_intr_alloc
+tries to allocate first.
+I.e., if the driver wants to allocate interrupt the following way:
+.Bd -literal
+	5 MSI-X
+	1 MSI (if MSI-X allocation failed)
+	INTx (if MSI allocation failed either)
+.Ed
+the driver should call
+.Fn pci_intr_alloc
+in the following way:
+.Bd -literal
+	int counts[PCI_INTR_TYPE_SIZE];
+	counts[PCI_INTR_TYPE_MSIX] = 5;
+	counts[PCI_INTR_TYPE_MSI] = 1;
+	counts[PCI_INTR_TYPE_INTX] = 1;
+	error = pci_intr_alloc(pa, ihps, counts,
+			       PCI_INTR_TYPE_MSIX);
+.Ed
+If the driver wants to allocate int the following way:
+.Bd -literal
+	hardware max number MSI-X
+	1 MSI (if MSI-X allocation failed)
+.Ed
+that is, the driver does not use INTx, the driver should call
+.Fn pci_intr_alloc
+in the following way:
+.Bd -literal
+	int counts[PCI_INTR_TYPE_SIZE];
+	counts[PCI_INTR_TYPE_MSIX] = -1; /* -1 means max */
+	counts[PCI_INTR_TYPE_MSI] = 1;
+	counts[PCI_INTR_TYPE_INTX] = 0; /* 0 means not use */
+	error = pci_intr_alloc(pa, ihps, counts,
+			       PCI_INTR_TYPE_MSIX);
+.Ed
+If the driver wants to allocate int the following way:
+.Bd -literal
+	3 MSI
+	INTx (if MSI allocation failed)
+.Ed
+that is, the driver does not use MSI-X, the driver should call
+.Fn pci_intr_alloc
+in the following way:
+.Bd -literal
+	int counts[PCI_INTR_TYPE_SIZE];
+	counts[PCI_INTR_TYPE_MSIX] = 0; /* 0 means not use */
+	counts[PCI_INTR_TYPE_MSI] = 3;
+	counts[PCI_INTR_TYPE_INTX] = 1;
+	error = pci_intr_alloc(pa, ihps, counts,
+			       PCI_INTR_TYPE_MSI);
+.Ed
+If the driver wants to allocate int the following way:
+.Bd -literal
+	1 MSI
+	INTx (if MSI allocation failed)
+.Ed
+that is, general usage, the driver should call simply
+.Fn pci_intr_alloc
+in the following way:
+.Bd -literal
+	error = pci_intr_alloc(pa, ihps, NULL, 0);
+.Ed
+.Fa max_type
+is ignored in this case.
+.Fn pci_intr_alloc
+return zero on any allocation function success, and nonzero on
+all allocation functions failure. On success,
+.Fa counts
+is overwritten by a really allocated count.
+I.e, if 5 MSI-X is allocated,
+.Fa counts
+is
+.Bd -literal
+	counts[PCI_INTR_TYPE_MSIX] == 5
+	counts[PCI_INTR_TYPE_MSI] == 0
+	counts[PCI_INTR_TYPE_INTX] == 0
+.Ed
+on return.
+.Pp
+.Ft pci_intr_type_t
+return the interrupt type of
+.Fa ih .
+The return value is
+.Dv PCI_INTR_TYPE_MSIX
+for MSI-X,
+.Dv PCI_INTR_TYPE_MSI
+for MSI
+.Dv PCI_INTR_TYPE_INTX
+for others.
 .Sh SEE ALSO
 .Xr pci_intr 9