linux-kernel - [RFC PATCH] PCI/MSI: Clarify usage of pci_msix_free

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <4c3e7a50d6e70f408812cd7ab199c6b4b326f9de.1676408572.git.reinette.chatre@intel.com>
Date:   Tue, 14 Feb 2023 13:13:20 -0800
From:   Reinette Chatre <reinette.chatre@...el.com>
To:     tglx@...utronix.de, darwi@...utronix.de, bhelgaas@...gle.com,
        maz@...nel.org, kevin.tian@...el.com, bagasdotme@...il.com
Cc:     jing2.liu@...el.com, reinette.chatre@...el.com,
        linux-pci@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [RFC PATCH] PCI/MSI: Clarify usage of pci_msix_free_irq()

pci_msix_free_irq() is used to free an interrupt on
a PCI/MSI-X interrupt domain.

The API description specifies that the interrupt to
be freed was allocated via pci_msix_alloc_irq_at().
This description limits the usage of pci_msix_free_irq()
since pci_msix_free_irq() can also be used to free
MSI-X interrupts allocated with, for example,
pci_alloc_irq_vectors().

Remove the text stating that the interrupt to be freed had
to be allocated with pci_msix_alloc_irq_at(). The needed
struct msi_map need not be from pci_msix_alloc_irq_at()
but can be created from scratch using pci_irq_vector()
to obtain the Linux IRQ number. Highlight that
pci_msix_free_irq() cannot be used to disable MSI-X to
guide users that, for example, pci_free_irq_vectors()
remains to be needed.

Signed-off-by: Reinette Chatre <reinette.chatre@...el.com>
---
Dear Maintainers,

Is my understanding correct?

For example, from my understanding the following is
correct API usage:

/*
 * Enable MSI-X and allocate num interrupts.
 */
pci_alloc_irq_vectors()

/*
 * Free one of the interrupts allocated via pci_alloc_irq_vectors().
 * Possibly called num times, but not required.
 */
pci_msix_free_irq()

/*
 * Ensure all remaining interrupts freed and MSI-X disabled.
 */
pci_free_irq_vectors()

This could be interpreted as an asymmetric usage of the API, yet
found to be practical when trying to use these new calls.

Your feedback is appreciated.

Regards,

Reinette

 drivers/pci/msi/api.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/pci/msi/api.c b/drivers/pci/msi/api.c
index b8009aa11f3c..be679aa5db64 100644
--- a/drivers/pci/msi/api.c
+++ b/drivers/pci/msi/api.c
@@ -163,11 +163,11 @@ EXPORT_SYMBOL_GPL(pci_msix_alloc_irq_at);

 /**
  * pci_msix_free_irq - Free an interrupt on a PCI/MSIX interrupt domain
- *		      which was allocated via pci_msix_alloc_irq_at()
  *
  * @dev:	The PCI device to operate on
  * @map:	A struct msi_map describing the interrupt to free
- *		as returned from the allocation function.
+ *
+ * Undo an interrupt vector allocation. Does not disable MSI-X.
  */
 void pci_msix_free_irq(struct pci_dev *dev, struct msi_map map)
 {
-- 
2.34.1