From b778cd42af80aa78b0ec03756987c99b9d511ed1 Mon Sep 17 00:00:00 2001
From: jhb <jhb@FreeBSD.org>
Date: Wed, 23 Dec 2015 21:51:10 +0000
Subject: Add accessor methods to fetch the BAR holding the MSI-X table and
 PBA.

While here, explicitly note the requirement that the BAR(s) must be
allocated prior to calling pci_alloc_msix().

Reviewed by:	andrew, emaste
MFC after:	1 week
Differential Revision:	https://reviews.freebsd.org/D4688
---
 share/man/man9/Makefile |  2 ++
 share/man/man9/pci.9    | 55 ++++++++++++++++++++++++++++++++++++++++++++++---
 2 files changed, 54 insertions(+), 3 deletions(-)

(limited to 'share')

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index c1399a3..3cd6f7f 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1287,6 +1287,8 @@ MLINKS+=pci.9 pci_alloc_msi.9 \
 	pci.9 pci_iov_detach.9 \
 	pci.9 pci_msi_count.9 \
 	pci.9 pci_msix_count.9 \
+	pci.9 pci_msix_pba_bar.9 \
+	pci.9 pci_msix_table_bar.9 \
 	pci.9 pci_pending_msix.9 \
 	pci.9 pci_read_config.9 \
 	pci.9 pci_release_msi.9 \
diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9
index 4faa5f2..ac7b28b 100644
--- a/share/man/man9/pci.9
+++ b/share/man/man9/pci.9
@@ -25,7 +25,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 5, 2015
+.Dd December 23, 2015
 .Dt PCI 9
 .Os
 .Sh NAME
@@ -51,6 +51,8 @@
 .Nm pci_iov_detach ,
 .Nm pci_msi_count ,
 .Nm pci_msix_count ,
+.Nm pci_msix_pba_bar ,
+.Nm pci_msix_table_bar ,
 .Nm pci_pending_msix ,
 .Nm pci_read_config ,
 .Nm pci_release_msi ,
@@ -107,6 +109,10 @@
 .Ft int
 .Fn pci_msix_count "device_t dev"
 .Ft int
+.Fn pci_msix_pba_bar "device_t dev"
+.Ft int
+.Fn pci_msix_table_bar "device_t dev"
+.Ft int
 .Fn pci_pending_msix "device_t dev" "u_int index"
 .Ft uint32_t
 .Fn pci_read_config "device_t dev" "int reg" "int width"
@@ -694,6 +700,37 @@ then
 returns zero.
 .Pp
 The
+.Fn pci_msix_pba_bar
+function returns the offset in configuration space of the Base Address Register
+.Pq BAR
+containing the MSI-X Pending Bit Array (PBA) for device
+.Fa dev .
+The returned value can be used as the resource ID with
+.Xr bus_alloc_resource 9
+and
+.Xr bus_release_resource 9
+to allocate the BAR.
+If the device does not support MSI-X,
+then
+.Fn pci_msix_pba_bar
+returns -1.
+.Pp
+The
+.Fn pci_msix_table_bar
+function returns the offset in configuration space of the BAR
+containing the MSI-X vector table for device
+.Fa dev .
+The returned value can be used as the resource ID with
+.Xr bus_alloc_resource 9
+and
+.Xr bus_release_resource 9
+to allocate the BAR.
+If the device does not support MSI-X,
+then
+.Fn pci_msix_table_bar
+returns -1.
+.Pp
+The
 .Fn pci_alloc_msix
 function attempts to allocate
 .Fa *count
@@ -732,12 +769,21 @@ it returns an error.
 Unlike MSI,
 MSI-X does not require message counts that are powers of two.
 .Pp
+The BARs containing the MSI-X vector table and PBA must be
+allocated via
+.Xr bus_alloc_resource 9
+before calling
+.Fn pci_alloc_msix
+and must not be released until after calling
+.Fn pci_release_msi .
+Note that the vector table and PBA may be stored in the same BAR or in
+different BARs.
+.Pp
 The
 .Fn pci_pending_msix
 function examines the
 .Fa dev
-device's Pending Bit Array
-.Pq PBA
+device's PBA
 to determine the pending status of the MSI-X message at table index
 .Fa index .
 If the indicated message is pending,
@@ -853,3 +899,6 @@ These do not refer to the geographic location of PCI devices,
 but to the device number assigned by the combination of the PCI IDSEL
 mechanism and the platform firmware.
 This should be taken note of when working with the kernel PCI code.
+.Pp
+The PCI bus driver should allocate the MSI-X vector table and PBA internally
+as necessary rather than requiring the caller to do so.
-- 
cgit v1.1