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

[Shawn Lin <shawn.lin@rock-chips.com>]

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