[PATCH v2 0/3] Clarify pci_free_irq_vectors() usage constraints

[PATCH v2 0/3] Clarify pci_free_irq_vectors() usage constraints

[Shawn Lin]

pcim_enable_device() automatically manages IRQ vectors, which can cause
double-free issues if drivers manually call pci_free_irq_vectors().

This series adds documentation and warnings to prevent this:
1. msi-howto.rst guidance
2. kernel-doc warning
3. TODO comment for future cleanup


Changes in v2:
- rework the commit message and documentation

Shawn Lin (3):
  Documentation: PCI: Clarify pci_free_irq_vectors() usage for managed
    devices
  PCI/MSI: Add warning to pci_free_irq_vectors() documentation
  PCI/MSI: Add TODO comment about legacy pcim_enable_device()
    side-effect

 Documentation/PCI/msi-howto.rst |  7 +++++--
 drivers/pci/msi/api.c           |  5 +++++
 drivers/pci/msi/msi.c           | 10 ++++++++++
 3 files changed, 20 insertions(+), 2 deletions(-)

-- 
2.7.4

[PATCH v2 1/3] Documentation: PCI: Clarify pci_free_irq_vectors() usage for managed devices

[Shawn Lin]

Update the msi-howto.rst 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>

---

Changes in v2:
- rework the commit message and documentation

 Documentation/PCI/msi-howto.rst | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/PCI/msi-howto.rst b/Documentation/PCI/msi-howto.rst
index 667ebe2..844c1d3 100644
--- 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);
 
-- 
2.7.4

[PATCH v2 2/3] PCI/MSI: Add warning to pci_free_irq_vectors() documentation

[Shawn Lin]

Update the kernel-doc comment for pci_free_irq_vectors() to warn drivers
that this function should not be called when the device has been enabled
with pcim_enable_device().

For legacy reasons, pcim_enable_device() activates automatic management
of IRQ vectors via pcim_msi_release(). Calling pci_free_irq_vectors() on
such devices can cause double-free issues.

This warning complements the documentation in msi-howto.rst and helps
developers who primarily read function API documentation when working
with the PCI/MSI subsystem.

Suggested-by: Philipp Stanner <phasta@kernel.org>
Signed-off-by: Shawn Lin <shawn.lin@rock-chips.com>
---

Changes in v2: None

 drivers/pci/msi/api.c | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/drivers/pci/msi/api.c b/drivers/pci/msi/api.c
index 818d55f..c18559b 100644
--- 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)
 {
-- 
2.7.4

[PATCH v2 3/3] PCI/MSI: Add TODO comment about legacy pcim_enable_device() side-effect

[Shawn Lin]

Add a TODO comment in pci/msi/msi.c to document that the automatic IRQ
vector management activated by pcim_enable_device() is a dangerous and
confusing.

The comment is placed near pcim_setup_msi_release() where the automatic
management is implemented, serving as a marker for future cleanup work.

Suggested-by: Philipp Stanner <phasta@kernel.org>
Signed-off-by: Shawn Lin <shawn.lin@rock-chips.com>

---

Changes in v2: None

 drivers/pci/msi/msi.c | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/drivers/pci/msi/msi.c b/drivers/pci/msi/msi.c
index e241217..81d24a2 100644
--- a/drivers/pci/msi/msi.c
+++ b/drivers/pci/msi/msi.c
@@ -77,6 +77,16 @@ static void pcim_msi_release(void *pcidev)
 /*
  * Needs to be separate from pcim_release to prevent an ordering problem
  * vs. msi_device_data_release() in the MSI core code.
+ *
+ * TODO: Remove the legacy side-effect of pcim_enable_device() that
+ * activates automatic IRQ vector management. This design is dangerous
+ * and confusing because it switches normally un-managed functions
+ * into managed mode. Drivers should explicitly manage their IRQ vectors
+ * without this implicit behavior.
+ *
+ * The current implementation uses both pdev->is_managed and
+ * pdev->is_msi_managed flags, which adds unnecessary complexity.
+ * This should be simplified in a future kernel version.
  */
 static int pcim_setup_msi_release(struct pci_dev *dev)
 {
-- 
2.7.4

Re: [PATCH v2 0/3] Clarify pci_free_irq_vectors() usage constraints

[Bjorn Helgaas]

On Wed, Feb 11, 2026 at 04:24:56PM +0800, Shawn Lin wrote:
> pcim_enable_device() automatically manages IRQ vectors, which can cause
> double-free issues if drivers manually call pci_free_irq_vectors().
> 
> This series adds documentation and warnings to prevent this:
> 1. msi-howto.rst guidance
> 2. kernel-doc warning
> 3. TODO comment for future cleanup
> 
> 
> Changes in v2:
> - rework the commit message and documentation
> 
> Shawn Lin (3):
>   Documentation: PCI: Clarify pci_free_irq_vectors() usage for managed
>     devices
>   PCI/MSI: Add warning to pci_free_irq_vectors() documentation
>   PCI/MSI: Add TODO comment about legacy pcim_enable_device()
>     side-effect
> 
>  Documentation/PCI/msi-howto.rst |  7 +++++--
>  drivers/pci/msi/api.c           |  5 +++++
>  drivers/pci/msi/msi.c           | 10 ++++++++++
>  3 files changed, 20 insertions(+), 2 deletions(-)

Squashed the first two patches and applied to pci/msi for v7.1,
thanks!

This will be rebased to v7.0-rc1 after it is tagged.