git: e5cbf0e881fa - main - pci: Add helper routines to manage PME in device drivers

The branch main has been updated by jhb:

URL: https://cgit.FreeBSD.org/src/commit/?id=e5cbf0e881fa1851912be77c62aa7ab17f844c3d

commit e5cbf0e881fa1851912be77c62aa7ab17f844c3d
Author:     John Baldwin <jhb@FreeBSD.org>
AuthorDate: 2025-03-27 20:53:58 +0000
Commit:     John Baldwin <jhb@FreeBSD.org>
CommitDate: 2025-03-27 20:55:03 +0000

    pci: Add helper routines to manage PME in device drivers
    
    pci_has_pm is a quick check that returns true if a PCI device supports
    the power management capability.
    
    pci_enable_pme can be used in DEVICE_SUSPEND driver methods to enable
    PME# during suspend.
    
    Reviewed by:    Krzysztof Galazka <krzysztof.galazka@intel.com>x
    Differential Revision:  https://reviews.freebsd.org/D49250
---
 share/man/man9/Makefile |  2 ++
 share/man/man9/pci.9    | 19 ++++++++++++++++++-
 sys/dev/pci/pci.c       | 24 ++++++++++++++++++++++++
 sys/dev/pci/pcivar.h    |  2 ++
 4 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 7b48a32b5387..a43d2c9fef3f 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1795,6 +1795,7 @@ MLINKS+=pci.9 pci_alloc_msi.9 \
 	pci.9 pci_disable_io.9 \
 	pci.9 pci_enable_busmaster.9 \
 	pci.9 pci_enable_io.9 \
+	pci.9 pci_enable_pme.9 \
 	pci.9 pci_find_bsf.9 \
 	pci.9 pci_find_cap.9 \
 	pci.9 pci_find_dbsf.9 \
@@ -1807,6 +1808,7 @@ MLINKS+=pci.9 pci_alloc_msi.9 \
 	pci.9 pci_get_powerstate.9 \
 	pci.9 pci_get_vpd_ident.9 \
 	pci.9 pci_get_vpd_readonly.9 \
+	pci.9 pci_has_pm.9 \
 	pci.9 pci_iov_attach.9 \
 	pci.9 pci_iov_attach_name.9 \
 	pci.9 pci_iov_detach.9 \
diff --git a/share/man/man9/pci.9 b/share/man/man9/pci.9
index 0f3fc92c23e7..8f772e76ba99 100644
--- a/share/man/man9/pci.9
+++ b/share/man/man9/pci.9
@@ -23,7 +23,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd May 20, 2021
+.Dd March 27, 2025
 .Dt PCI 9
 .Os
 .Sh NAME
@@ -35,6 +35,7 @@
 .Nm pci_disable_io ,
 .Nm pci_enable_busmaster ,
 .Nm pci_enable_io ,
+.Nm pci_enable_pme ,
 .Nm pci_find_bsf ,
 .Nm pci_find_cap ,
 .Nm pci_find_dbsf ,
@@ -51,6 +52,7 @@
 .Nm pci_get_powerstate ,
 .Nm pci_get_vpd_ident ,
 .Nm pci_get_vpd_readonly ,
+.Nm pci_has_pm ,
 .Nm pci_iov_attach ,
 .Nm pci_iov_attach_name ,
 .Nm pci_iov_detach ,
@@ -92,6 +94,8 @@
 .Fn pci_enable_busmaster "device_t dev"
 .Ft int
 .Fn pci_enable_io "device_t dev" "int space"
+.Ft void
+.Fn pci_enable_pme "device_t dev"
 .Ft device_t
 .Fn pci_find_bsf "uint8_t bus" "uint8_t slot" "uint8_t func"
 .Ft int
@@ -124,6 +128,8 @@
 .Fn pci_get_vpd_ident "device_t dev" "const char **identptr"
 .Ft int
 .Fn pci_get_vpd_readonly "device_t dev" "const char *kw" "const char **vptr"
+.Ft bool
+.Fn pci_has_pm "device_t dev"
 .Ft int
 .Fn pci_msi_count "device_t dev"
 .Ft int
@@ -358,6 +364,12 @@ When no more instances are located
 returns an error.
 .Pp
 The
+.Fn pci_has_pm
+function returns true if
+.Fa dev
+supports power management.
+.Pp
+The
 .Fn pci_find_extcap
 function is used to locate the first instance of a PCI-express
 extended capability register set for the device
@@ -678,6 +690,11 @@ function is used to clear any pending PME# signal and disable generation
 of power management events.
 .Pp
 The
+.Fn pci_enable_pme
+function is used to enable generation of power management events before
+suspending a device.
+.Pp
+The
 .Fn pci_iov_attach
 function is used to advertise that the given device
 .Pq and associated device driver
diff --git a/sys/dev/pci/pci.c b/sys/dev/pci/pci.c
index 4c7ca27d8e64..2ee2f10924aa 100644
--- a/sys/dev/pci/pci.c
+++ b/sys/dev/pci/pci.c
@@ -2952,6 +2952,30 @@ pci_clear_pme(device_t dev)
 	}
 }
 
+/* Clear any active PME# and enable PME# generation. */
+void
+pci_enable_pme(device_t dev)
+{
+	struct pci_devinfo *dinfo = device_get_ivars(dev);
+	pcicfgregs *cfg = &dinfo->cfg;
+	uint16_t status;
+
+	if (cfg->pp.pp_cap != 0) {
+		status = pci_read_config(dev, dinfo->cfg.pp.pp_status, 2);
+		status |= PCIM_PSTAT_PME | PCIM_PSTAT_PMEENABLE;
+		pci_write_config(dev, dinfo->cfg.pp.pp_status, status, 2);
+	}
+}
+
+bool
+pci_has_pm(device_t dev)
+{
+	struct pci_devinfo *dinfo = device_get_ivars(dev);
+	pcicfgregs *cfg = &dinfo->cfg;
+
+	return (cfg->pp.pp_cap != 0);
+}
+
 /*
  * Some convenience functions for PCI device drivers.
  */
diff --git a/sys/dev/pci/pcivar.h b/sys/dev/pci/pcivar.h
index 1f99e9830930..01fd67edb58d 100644
--- a/sys/dev/pci/pcivar.h
+++ b/sys/dev/pci/pcivar.h
@@ -687,6 +687,8 @@ void	pci_save_state(device_t dev);
 int	pci_set_max_read_req(device_t dev, int size);
 int	pci_power_reset(device_t dev);
 void	pci_clear_pme(device_t dev);
+void	pci_enable_pme(device_t dev);
+bool	pci_has_pm(device_t dev);
 uint32_t pcie_read_config(device_t dev, int reg, int width);
 void	pcie_write_config(device_t dev, int reg, uint32_t value, int width);
 uint32_t pcie_adjust_config(device_t dev, int reg, uint32_t mask,