1 // SPDX-License-Identifier: GPL-2.0
3  * PCI MSI/MSI-X — Exported APIs for device drivers
5  * Copyright (C) 2003-2004 Intel
17  * pci_enable_msi() - Enable MSI interrupt mode on device
22  * Linux IRQ will be saved at @dev->irq. The driver must invoke
40  * pci_disable_msi() - Disable MSI interrupt mode on device
45  * The PCI device Linux IRQ (@dev->irq) is restored to its default
46  * pin-assertion IRQ. This is the cleanup pair of pci_enable_msi().
53 	if (!pci_msi_enabled() || !dev || !dev->msi_enabled)  in pci_disable_msi()
56 	guard(msi_descs_lock)(&dev->dev);  in pci_disable_msi()
63  * pci_msix_vec_count() - Get number of MSI-X interrupt vectors on device
66  * Return: number of MSI-X interrupt vectors available on this device
67  * (i.e., the device's MSI-X capability structure "table size"), -EINVAL
68  * if the device is not MSI-X capable, other errnos otherwise.
74 	if (!dev->msix_cap)  in pci_msix_vec_count()
75 		return -EINVAL;  in pci_msix_vec_count()
77 	pci_read_config_word(dev, dev->msix_cap + PCI_MSIX_FLAGS, &control);  in pci_msix_vec_count()
83  * pci_enable_msix_range() - Enable MSI-X interrupt mode on device
85  * @entries: input/output parameter, array of MSI-X configuration entries
86  * @minvec:  minimum required number of MSI-X vectors
87  * @maxvec:  maximum desired number of MSI-X vectors
89  * Legacy device driver API to enable MSI-X interrupt mode on device and
90  * configure its MSI-X capability structure as appropriate.  The passed
92  * desired (valid) MSI-X vector number, where the range of valid MSI-X
99  * Return: number of MSI-X vectors allocated (which might be smaller
102  * -ENOSPC if less than @minvecs interrupt vectors are available.
103  * Return -EINVAL if one of the passed @entries members "entry" field
115  * pci_msix_can_alloc_dyn - Query whether dynamic allocation after enabling
116  *			    MSI-X is supported
124 	if (!dev->msix_cap)  in pci_msix_can_alloc_dyn()
132  * pci_msix_alloc_irq_at - Allocate an MSI-X interrupt after enabling MSI-X
133  *			   at a given MSI-X vector index or any free vector index
137  *		the next free index in the MSI-X table
151 	struct msi_map map = { .index = -ENOTSUPP };  in pci_msix_alloc_irq_at()
153 	if (!dev->msix_enabled)  in pci_msix_alloc_irq_at()
159 	return msi_domain_alloc_irq_at(&dev->dev, MSI_DEFAULT_DOMAIN, index, affdesc, NULL);  in pci_msix_alloc_irq_at()
164  * pci_msix_free_irq - Free an interrupt on a PCI/MSI-X interrupt domain
169  * Undo an interrupt vector allocation. Does not disable MSI-X.
177 	msi_domain_free_irqs_range(&dev->dev, MSI_DEFAULT_DOMAIN, map.index, map.index);  in pci_msix_free_irq()
182  * pci_disable_msix() - Disable MSI-X interrupt mode on device
185  * Legacy device driver API to disable MSI-X interrupt mode on device,
186  * free earlier-allocated interrupt vectors, and restore INTx.
187  * The PCI device Linux IRQ (@dev->irq) is restored to its default pin
195 	if (!pci_msi_enabled() || !dev || !dev->msix_enabled)  in pci_disable_msix()
198 	guard(msi_descs_lock)(&dev->dev);  in pci_disable_msix()
205  * pci_alloc_irq_vectors() - Allocate multiple device interrupt vectors
211  *            * %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
217  *            * %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
220  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
229  * @max_vecs), -ENOSPC if less than @min_vecs interrupt vectors are
241  * pci_alloc_irq_vectors_affinity() - Allocate multiple device interrupt
257 	int nvecs = -ENOSPC;  in pci_alloc_irq_vectors_affinity()
282 		if (min_vecs == 1 && dev->irq) {  in pci_alloc_irq_vectors_affinity()
300  * pci_irq_vector() - Get Linux IRQ number of a device interrupt vector
302  * @nr:  device-relative interrupt vector index (0-based); has different
305  *         * MSI-X     the index in the MSI-X vector table
309  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
311 int pci_irq_vector(struct pci_dev *dev, unsigned int nr)  in pci_irq_vector()  argument
315 	if (!dev->msi_enabled && !dev->msix_enabled)  in pci_irq_vector()
316 		return !nr ? dev->irq : -EINVAL;  in pci_irq_vector()
318 	irq = msi_get_virq(&dev->dev, nr);  in pci_irq_vector()
319 	return irq ? irq : -EINVAL;  in pci_irq_vector()
324  * pci_irq_get_affinity() - Get a device interrupt vector affinity
326  * @nr:  device-relative interrupt vector index (0-based); has different
329  *         * MSI-X     the index in the MSI-X vector table
333  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
334  * the MSI(-X) vector was allocated without explicit affinity
340 const struct cpumask *pci_irq_get_affinity(struct pci_dev *dev, int nr)  in pci_irq_get_affinity()  argument
342 	int idx, irq = pci_irq_vector(dev, nr);  in pci_irq_get_affinity()
349 	/* Non-MSI does not have the information handy */  in pci_irq_get_affinity()
354 	if (!desc->affinity)  in pci_irq_get_affinity()
359 	 * MSI-X has a single mask.  in pci_irq_get_affinity()
361 	idx = dev->msi_enabled ? nr : 0;  in pci_irq_get_affinity()
362 	return &desc->affinity[idx].mask;  in pci_irq_get_affinity()
367  * pci_free_irq_vectors() - Free previously allocated IRQs for a device
370  * Undo the interrupt vector allocations and possible device MSI/MSI-X
382  * pci_restore_msi_state() - Restore cached MSI(-X) state on device
385  * Write the Linux-cached MSI(-X) state back on device. This is
386  * typically useful upon system resume, or after an error-recovery PCI
397  * pci_msi_enabled() - Are MSI(-X) interrupts enabled system-wide?
400  * PCI bridge quirks, or the "pci=nomsi" kernel command-line option.