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
18  * @dev: the PCI device to operate on
20  * Legacy device driver API to enable MSI interrupts mode on device and
21  * allocate a single interrupt vector. On success, the allocated vector
22  * Linux IRQ will be saved at @dev->irq. The driver must invoke
23  * pci_disable_msi() on cleanup.
28  * Return: 0 on success, errno otherwise
40  * pci_disable_msi() - Disable MSI interrupt mode on device
41  * @dev: the PCI device to operate on
43  * Legacy device driver API to 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 	msi_lock_descs(&dev->dev);  in pci_disable_msi()
59 	msi_unlock_descs(&dev->dev);  in pci_disable_msi()
64  * pci_msix_vec_count() - Get number of MSI-X interrupt vectors on device
65  * @dev: the PCI device to operate on
67  * Return: number of MSI-X interrupt vectors available on this device
68  * (i.e., the device's MSI-X capability structure "table size"), -EINVAL
69  * if the device is not MSI-X capable, other errnos otherwise.
75 	if (!dev->msix_cap)  in pci_msix_vec_count()
76 		return -EINVAL;  in pci_msix_vec_count()
78 	pci_read_config_word(dev, dev->msix_cap + PCI_MSIX_FLAGS, &control);  in pci_msix_vec_count()
84  * pci_enable_msix_range() - Enable MSI-X interrupt mode on device
85  * @dev:     the PCI device to operate on
86  * @entries: input/output parameter, array of MSI-X configuration entries
87  * @minvec:  minimum required number of MSI-X vectors
88  * @maxvec:  maximum desired number of MSI-X vectors
90  * Legacy device driver API to enable MSI-X interrupt mode on device and
91  * configure its MSI-X capability structure as appropriate.  The passed
93  * desired (valid) MSI-X vector number, where the range of valid MSI-X
95  * successful, the driver must invoke pci_disable_msix() on cleanup.
100  * Return: number of MSI-X vectors allocated (which might be smaller
103  * -ENOSPC if less than @minvecs interrupt vectors are available.
104  * Return -EINVAL if one of the passed @entries members "entry" field
106  * earlier enabled on device. Return other errnos otherwise.
116  * pci_msix_can_alloc_dyn - Query whether dynamic allocation after enabling
117  *			    MSI-X is supported
119  * @dev:	PCI device to operate on
125 	if (!dev->msix_cap)  in pci_msix_can_alloc_dyn()
133  * pci_msix_alloc_irq_at - Allocate an MSI-X interrupt after enabling MSI-X
134  *			   at a given MSI-X vector index or any free vector index
136  * @dev:	PCI device to operate on
138  *		the next free index in the MSI-X table
143  *	On success msi_map::index contains the allocated index (>= 0) and
146  *	On fail msi_map::index contains the error code and msi_map::virq
152 	struct msi_map map = { .index = -ENOTSUPP };  in pci_msix_alloc_irq_at()
154 	if (!dev->msix_enabled)  in pci_msix_alloc_irq_at()
160 	return msi_domain_alloc_irq_at(&dev->dev, MSI_DEFAULT_DOMAIN, index, affdesc, NULL);  in pci_msix_alloc_irq_at()
165  * pci_msix_free_irq - Free an interrupt on a PCI/MSIX interrupt domain
167  * @dev:	The PCI device to operate on
170  * Undo an interrupt vector allocation. Does not disable MSI-X.
178 	msi_domain_free_irqs_range(&dev->dev, MSI_DEFAULT_DOMAIN, map.index, map.index);  in pci_msix_free_irq()
183  * pci_disable_msix() - Disable MSI-X interrupt mode on device
184  * @dev: the PCI device to operate on
186  * Legacy device driver API to disable MSI-X interrupt mode on device,
187  * free earlier-allocated interrupt vectors, and restore INTx.
188  * The PCI device Linux IRQ (@dev->irq) is restored to its default pin
196 	if (!pci_msi_enabled() || !dev || !dev->msix_enabled)  in pci_disable_msix()
199 	msi_lock_descs(&dev->dev);  in pci_disable_msix()
202 	msi_unlock_descs(&dev->dev);  in pci_disable_msix()
207  * pci_alloc_irq_vectors() - Allocate multiple device interrupt vectors
208  * @dev:      the PCI device to operate on
213  *            * %PCI_IRQ_MSIX      Allow trying MSI-X vector allocations
219  *            * %PCI_IRQ_AFFINITY  Auto-manage IRQs affinity by spreading
222  * Allocate up to @max_vecs interrupt vectors on device. MSI-X irq
228  * The driver must call pci_free_irq_vectors() on cleanup.
231  * @max_vecs), -ENOSPC if less than @min_vecs interrupt vectors are
243  * pci_alloc_irq_vectors_affinity() - Allocate multiple device interrupt
245  * @dev:      the PCI device to operate on
259 	int nvecs = -ENOSPC;  in pci_alloc_irq_vectors_affinity()
284 		if (min_vecs == 1 && dev->irq) {  in pci_alloc_irq_vectors_affinity()
287 			 * the device driver can adjust queue configuration  in pci_alloc_irq_vectors_affinity()
302  * pci_irq_vector() - Get Linux IRQ number of a device interrupt vector
303  * @dev: the PCI device to operate on
304  * @nr:  device-relative interrupt vector index (0-based); has different
305  *       meanings, depending on interrupt mode:
307  *         * MSI-X     the index in the MSI-X vector table
311  * Return: the Linux IRQ number, or -EINVAL if @nr is out of range
317 	if (!dev->msi_enabled && !dev->msix_enabled)  in pci_irq_vector()
318 		return !nr ? dev->irq : -EINVAL;  in pci_irq_vector()
320 	irq = msi_get_virq(&dev->dev, nr);  in pci_irq_vector()
321 	return irq ? irq : -EINVAL;  in pci_irq_vector()
326  * pci_irq_get_affinity() - Get a device interrupt vector affinity
327  * @dev: the PCI device to operate on
328  * @nr:  device-relative interrupt vector index (0-based); has different
329  *       meanings, depending on interrupt mode:
331  *         * MSI-X     the index in the MSI-X vector table
335  * Return: MSI/MSI-X vector affinity, NULL if @nr is out of range or if
336  * the MSI(-X) vector was allocated without explicit affinity
340  * during system boot if the device is in legacy INTx mode.
351 	/* Non-MSI does not have the information handy */  in pci_irq_get_affinity()
356 	if (!desc->affinity)  in pci_irq_get_affinity()
361 	 * MSI-X has a single mask.  in pci_irq_get_affinity()
363 	idx = dev->msi_enabled ? nr : 0;  in pci_irq_get_affinity()
364 	return &desc->affinity[idx].mask;  in pci_irq_get_affinity()
369  * pci_free_irq_vectors() - Free previously allocated IRQs for a device
370  * @dev: the PCI device to operate on
372  * Undo the interrupt vector allocations and possible device MSI/MSI-X
384  * pci_restore_msi_state() - Restore cached MSI(-X) state on device
385  * @dev: the PCI device to operate on
387  * Write the Linux-cached MSI(-X) state back on device. This is
388  * typically useful upon system resume, or after an error-recovery PCI
399  * pci_msi_enabled() - Are MSI(-X) interrupts enabled system-wide?
402  * PCI bridge quirks, or the "pci=nomsi" kernel command-line option.