Module Name: src
Committed By: knakahara
Date: Tue Jul 21 03:12:50 UTC 2015
Modified Files:
src/distrib/sets/lists/comp: mi
src/share/man/man9: Makefile pci_msi.9
Log Message:
add pci_intr_alloc() man
To generate a diff of this commit:
cvs rdiff -u -r1.1970 -r1.1971 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.388 -r1.389 src/share/man/man9/Makefile
cvs rdiff -u -r1.3 -r1.4 src/share/man/man9/pci_msi.9
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1970 src/distrib/sets/lists/comp/mi:1.1971
--- src/distrib/sets/lists/comp/mi:1.1970 Sun Jul 12 08:11:27 2015
+++ src/distrib/sets/lists/comp/mi Tue Jul 21 03:12:50 2015
@@ -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
Index: src/share/man/man9/Makefile
diff -u src/share/man/man9/Makefile:1.388 src/share/man/man9/Makefile:1.389
--- src/share/man/man9/Makefile:1.388 Sun Jul 12 08:11:27 2015
+++ src/share/man/man9/Makefile Tue Jul 21 03:12:50 2015
@@ -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 @@ MLINKS+=pci.9 pci_conf_read.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 \
Index: src/share/man/man9/pci_msi.9
diff -u src/share/man/man9/pci_msi.9:1.3 src/share/man/man9/pci_msi.9:1.4
--- src/share/man/man9/pci_msi.9:1.3 Fri May 15 08:39:14 2015
+++ src/share/man/man9/pci_msi.9 Tue Jul 21 03:12:50 2015
@@ -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 @@ in contrast,
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
