PCI/MSI: Clarify pci_free_irq_vectors() usage for managed devices

Update pci_free_irq_vectors() documentation to clarify that drivers using
pcim_enable_device() must not call pci_free_irq_vectors().

For legacy reasons, pcim_enable_device() switches several normally
un-managed functions into managed mode. Currently, the only function
affected in this way is pcim_setup_msi_release(), which results in
automatic IRQ vector management.

This behavior is dangerous and confusing. Drivers using pcim_enable_device()
should rely on the automatic IRQ vector management and avoid calling
pci_free_irq_vectors() manually.

Suggested-by: Philipp Stanner <phasta@kernel.org>
Signed-off-by: Shawn Lin <shawn.lin@rock-chips.com>
[bhelgaas: squash both updates to pci_free_irq_vectors() documentation]
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://patch.msgid.link/1770798299-202288-2-git-send-email-shawn.lin@rock-chips.com
Link: https://patch.msgid.link/1770798299-202288-3-git-send-email-shawn.lin@rock-chips.com

diff --git a/Documentation/PCI/msi-howto.rst b/Documentation/PCI/msi-howto.rst
index 667ebe2156b476f99f4ed6fa80ee07fb92beaad1..844c1d3c395ddbea52a08f8d1dd0ac4aa831c880 100644 (file)
--- a/Documentation/PCI/msi-howto.rst
+++ b/Documentation/PCI/msi-howto.rst
@@ -113,8 +113,11 @@ vectors, use the following function::
 
   int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
 
-Any allocated resources should be freed before removing the device using
-the following function::
+If the driver enables the device using pcim_enable_device(), the driver
+shouldn't call pci_free_irq_vectors() because pcim_enable_device()
+activates automatic management for IRQ vectors. Otherwise, the driver should
+free any allocated IRQ vectors before removing the device using the following
+function::
 
   void pci_free_irq_vectors(struct pci_dev *dev);
 

diff --git a/drivers/pci/msi/api.c b/drivers/pci/msi/api.c
index 818d55fbad0dfa727b9e2113945ae80dcbe37fb0..c18559b6272c0caab5381045c9f25b1225750f70 100644 (file)
--- a/drivers/pci/msi/api.c
+++ b/drivers/pci/msi/api.c
@@ -370,6 +370,11 @@ EXPORT_SYMBOL(pci_irq_get_affinity);
  * Undo the interrupt vector allocations and possible device MSI/MSI-X
  * enablement earlier done through pci_alloc_irq_vectors_affinity() or
  * pci_alloc_irq_vectors().
+ *
+ * WARNING: Do not call this function if the device has been enabled
+ * with pcim_enable_device(). In that case, IRQ vectors are automatically
+ * managed via pcim_msi_release() and calling pci_free_irq_vectors() can
+ * lead to double-free issues.
  */
 void pci_free_irq_vectors(struct pci_dev *dev)
 {