4. The MSI Driver Guide HOWTO — The Linux Kernel documentation (2024)

Authors:

Tom L Nguyen; Martine Silbermann; Matthew Wilcox

Copyright:

2003, 2008 Intel Corporation

4.1. About this guide

This guide describes the basics of Message Signaled Interrupts (MSIs),the advantages of using MSI over traditional interrupt mechanisms, howto change your driver to use MSI or MSI-X and some basic diagnostics totry if a device doesn’t support MSIs.

4.2. What are MSIs?

A Message Signaled Interrupt is a write from the device to a specialaddress which causes an interrupt to be received by the CPU.

The MSI capability was first specified in PCI 2.2 and was later enhancedin PCI 3.0 to allow each interrupt to be masked individually. The MSI-Xcapability was also introduced with PCI 3.0. It supports more interruptsper device than MSI and allows interrupts to be independently configured.

Devices may support both MSI and MSI-X, but only one can be enabled ata time.

4.3. Why use MSIs?

There are three reasons why using MSIs can give an advantage overtraditional pin-based interrupts.

Pin-based PCI interrupts are often shared amongst several devices.To support this, the kernel must call each interrupt handler associatedwith an interrupt, which leads to reduced performance for the system asa whole. MSIs are never shared, so this problem cannot arise.

When a device writes data to memory, then raises a pin-based interrupt,it is possible that the interrupt may arrive before all the data hasarrived in memory (this becomes more likely with devices behind PCI-PCIbridges). In order to ensure that all the data has arrived in memory,the interrupt handler must read a register on the device which raisedthe interrupt. PCI transaction ordering rules require that all the dataarrive in memory before the value may be returned from the register.Using MSIs avoids this problem as the interrupt-generating write cannotpass the data writes, so by the time the interrupt is raised, the driverknows that all the data has arrived in memory.

PCI devices can only support a single pin-based interrupt per function.Often drivers have to query the device to find out what event hasoccurred, slowing down interrupt handling for the common case. WithMSIs, a device can support more interrupts, allowing each interruptto be specialised to a different purpose. One possible design givesinfrequent conditions (such as errors) their own interrupt which allowsthe driver to handle the normal interrupt handling path more efficiently.Other possible designs include giving one interrupt to each packet queuein a network card or each port in a storage controller.

4.4. How to use MSIs

PCI devices are initialised to use pin-based interrupts. The devicedriver has to set up the device to use MSI or MSI-X. Not all machinessupport MSIs correctly, and for those machines, the APIs described belowwill simply fail and the device will continue to use pin-based interrupts.

4.4.1. Include kernel support for MSIs

To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSIoption enabled. This option is only available on some architectures,and it may depend on some other options also being set. For example,on x86, you must also enable X86_UP_APIC or SMP in order to see theCONFIG_PCI_MSI option.

4.4.2. Using MSI

Most of the hard work is done for the driver in the PCI layer. The driversimply has to request that the PCI layer set up the MSI capability for thisdevice.

To automatically use MSI or MSI-X interrupt vectors, use the followingfunction:

int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags);

which allocates up to max_vecs interrupt vectors for a PCI device. Itreturns the number of vectors allocated or a negative error. If the devicehas a requirements for a minimum number of vectors the driver can pass amin_vecs argument set to this limit, and the PCI core will return -ENOSPCif it can’t meet the minimum number of vectors.

The flags argument is used to specify which type of interrupt can be usedby the device and the driver (PCI_IRQ_INTX, PCI_IRQ_MSI, PCI_IRQ_MSIX).A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask forany possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.

To get the Linux IRQ numbers passed to request_irq() and free_irq() and thevectors, 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 usingthe following function:

void pci_free_irq_vectors(struct pci_dev *dev);

If a device supports both MSI-X and MSI capabilities, this API will use theMSI-X facilities in preference to the MSI facilities. MSI-X supports anynumber of interrupts between 1 and 2048. In contrast, MSI is restricted toa maximum of 32 interrupts (and must be a power of two). In addition, theMSI interrupt vectors must be allocated consecutively, so the system mightnot be able to allocate as many vectors for MSI as it could for MSI-X. Onsome platforms, MSI interrupts must all be targeted at the same set of CPUswhereas MSI-X interrupts can all be targeted at different CPUs.

If a device supports neither MSI-X or MSI it will fall back to a singlelegacy IRQ vector.

The typical usage of MSI or MSI-X interrupts is to allocate as many vectorsas possible, likely up to the limit supported by the device. If nvec islarger than the number supported by the device it will automatically becapped to the supported limit, so there is no need to query the number ofvectors supported beforehand:

nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)if (nvec < 0) goto out_err;

If a driver is unable or unwilling to deal with a variable number of MSIinterrupts it can request a particular number of interrupts by passing thatnumber to pci_alloc_irq_vectors() function as both ‘min_vecs’ and‘max_vecs’ parameters:

ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);if (ret < 0) goto out_err;

The most notorious example of the request type described above is enablingthe single MSI mode for a device. It could be done by passing two 1s as‘min_vecs’ and ‘max_vecs’:

ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);if (ret < 0) goto out_err;

Some devices might not support using legacy line interrupts, in which casethe driver can specify that only MSI or MSI-X is acceptable:

nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);if (nvec < 0) goto out_err;

4.4.3. Legacy APIs

The following old APIs to enable and disable MSI or MSI-X interrupts shouldnot be used in new code:

pci_enable_msi() /* deprecated */pci_disable_msi() /* deprecated */pci_enable_msix_range() /* deprecated */pci_enable_msix_exact() /* deprecated */pci_disable_msix() /* deprecated */

Additionally there are APIs to provide the number of supported MSI or MSI-Xvectors: pci_msi_vec_count() and pci_msix_vec_count(). In general theseshould be avoided in favor of letting pci_alloc_irq_vectors() cap thenumber of vectors. If you have a legitimate special use case for the countof vectors we might have to revisit that decision and add apci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.

4.4.4. Considerations when using MSIs

4.4.4.1. Spinlocks

Most device drivers have a per-device spinlock which is taken in theinterrupt handler. With pin-based interrupts or a single MSI, it is notnecessary to disable interrupts (Linux guarantees the same interrupt willnot be re-entered). If a device uses multiple interrupts, the drivermust disable interrupts while the lock is held. If the device sendsa different interrupt, the driver will deadlock trying to recursivelyacquire the spinlock. Such deadlocks can be avoided by usingspin_lock_irqsave() or spin_lock_irq() which disable local interruptsand acquire the lock (see Unreliable Guide To Locking).

4.4.5. How to tell whether MSI/MSI-X is enabled on a device

Using ‘lspci -v’ (as root) may show some devices with “MSI”, “MessageSignalled Interrupts” or “MSI-X” capabilities. Each of these capabilitieshas an ‘Enable’ flag which is followed with either “+” (enabled)or “-” (disabled).

4.5. MSI quirks

Several PCI chipsets or devices are known not to support MSIs.The PCI stack provides three ways to disable MSIs:

  1. globally

  2. on all devices behind a specific bridge

  3. on a single device

4.5.1. Disabling MSIs globally

Some host chipsets simply don’t support MSIs properly. If we’relucky, the manufacturer knows this and has indicated it in the ACPIFADT table. In this case, Linux automatically disables MSIs.Some boards don’t include this information in the table and so we haveto detect them ourselves. The complete list of these is found near thequirk_disable_all_msi() function in drivers/pci/quirks.c.

If you have a board which has problems with MSIs, you can pass pci=nomsion the kernel command line to disable MSIs on all devices. It would bein your best interests to report the problem to linux-pci@vger.kernel.orgincluding a full ‘lspci -v’ so we can add the quirks to the kernel.

4.5.2. Disabling MSIs below a bridge

Some PCI bridges are not able to route MSIs between buses properly.In this case, MSIs must be disabled on all devices behind the bridge.

Some bridges allow you to enable MSIs by changing some bits in theirPCI configuration space (especially the Hypertransport chipsets suchas the nVidia nForce and Serverworks HT2000). As with host chipsets,Linux mostly knows about them and automatically enables MSIs if it can.If you have a bridge unknown to Linux, you can enableMSIs in configuration space using whatever method you know works, thenenable MSIs on that bridge by doing:

echo 1 > /sys/bus/pci/devices/$bridge/msi_bus

where $bridge is the PCI address of the bridge you’ve enabled (eg0000:00:0e.0).

To disable MSIs, echo 0 instead of 1. Changing this value should bedone with caution as it could break interrupt handling for all devicesbelow this bridge.

Again, please notify linux-pci@vger.kernel.org of any bridges that needspecial handling.

4.5.3. Disabling MSIs on a single device

Some devices are known to have faulty MSI implementations. Usually thisis handled in the individual device driver, but occasionally it’s necessaryto handle this with a quirk. Some drivers have an option to disable useof MSI. While this is a convenient workaround for the driver author,it is not good practice, and should not be emulated.

4.5.4. Finding why MSIs are disabled on a device

From the above three sections, you can see that there are many reasonswhy MSIs may not be enabled for a given device. Your first step shouldbe to examine your dmesg carefully to determine whether MSIs are enabledfor your machine. You should also check your .config to be sure youhave enabled CONFIG_PCI_MSI.

Then, ‘lspci -t’ gives the list of bridges above a device. Reading/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)or disabled (0). If 0 is found in any of the msi_bus files belongingto bridges between the PCI root and the device, MSIs are disabled.

It is also worth checking the device driver to see whether it supports MSIs.For example, it may contain calls to pci_alloc_irq_vectors() with thePCI_IRQ_MSI or PCI_IRQ_MSIX flags.

4.6. List of device drivers MSI(-X) APIs

The PCI/MSI subsystem has a dedicated C file for its exported device driverAPIs — drivers/pci/msi/api.c. The following functions are exported:

int pci_enable_msi(struct pci_dev *dev)

Enable MSI interrupt mode on device

Parameters

struct pci_dev *dev

the PCI device to operate on

Description

Legacy device driver API to enable MSI interrupts mode on device andallocate a single interrupt vector. On success, the allocated vectorLinux IRQ will be saved at dev->irq. The driver must invokepci_disable_msi() on cleanup.

NOTE

The newer pci_alloc_irq_vectors() / pci_free_irq_vectors() APIpair should, in general, be used instead.

Return

0 on success, errno otherwise

void pci_disable_msi(struct pci_dev *dev)

Disable MSI interrupt mode on device

Parameters

struct pci_dev *dev

the PCI device to operate on

Description

Legacy device driver API to disable MSI interrupt mode on device,free earlier allocated interrupt vectors, and restore INTx emulation.The PCI device Linux IRQ (dev->irq) is restored to its defaultpin-assertion IRQ. This is the cleanup pair of pci_enable_msi().

NOTE

The newer pci_alloc_irq_vectors() / pci_free_irq_vectors() APIpair should, in general, be used instead.

int pci_msix_vec_count(struct pci_dev *dev)

Get number of MSI-X interrupt vectors on device

Parameters

struct pci_dev *dev

the PCI device to operate on

Return

number of MSI-X interrupt vectors available on this device(i.e., the device’s MSI-X capability structure “table size”), -EINVALif the device is not MSI-X capable, other errnos otherwise.

int pci_enable_msix_range(struct pci_dev *dev, struct msix_entry *entries, int minvec, int maxvec)

Enable MSI-X interrupt mode on device

Parameters

struct pci_dev *dev

the PCI device to operate on

struct msix_entry *entries

input/output parameter, array of MSI-X configuration entries

int minvec

minimum required number of MSI-X vectors

int maxvec

maximum desired number of MSI-X vectors

Description

Legacy device driver API to enable MSI-X interrupt mode on device andconfigure its MSI-X capability structure as appropriate. The passedentries array must have each of its members “entry” field set to adesired (valid) MSI-X vector number, where the range of valid MSI-Xvector numbers can be queried through pci_msix_vec_count(). Ifsuccessful, the driver must invoke pci_disable_msix() on cleanup.

NOTE

The newer pci_alloc_irq_vectors() / pci_free_irq_vectors() APIpair should, in general, be used instead.

Return

number of MSI-X vectors allocated (which might be smallerthan maxvecs), where Linux IRQ numbers for such allocated vectorsare saved back in the entries array elements’ “vector” field. Return-ENOSPC if less than minvecs interrupt vectors are available.Return -EINVAL if one of the passed entries members “entry” fieldwas invalid or a duplicate, or if plain MSI interrupts mode wasearlier enabled on device. Return other errnos otherwise.

bool pci_msix_can_alloc_dyn(struct pci_dev *dev)

Query whether dynamic allocation after enabling MSI-X is supported

Parameters

struct pci_dev *dev

PCI device to operate on

Return

True if supported, false otherwise

struct msi_map pci_msix_alloc_irq_at(struct pci_dev *dev, unsigned int index, const struct irq_affinity_desc *affdesc)

Allocate an MSI-X interrupt after enabling MSI-X at a given MSI-X vector index or any free vector index

Parameters

struct pci_dev *dev

PCI device to operate on

unsigned int index

Index to allocate. If index == MSI_ANY_INDEX this allocatesthe next free index in the MSI-X table

const struct irq_affinity_desc *affdesc

Optional pointer to an affinity descriptor structure. NULL otherwise

Return

A struct msi_map

On success msi_map::index contains the allocated index (>= 0) andmsi_map::virq contains the allocated Linux interrupt number (> 0).

On fail msi_map::index contains the error code and msi_map::virqis set to 0.

void pci_msix_free_irq(struct pci_dev *dev, struct msi_map map)

Free an interrupt on a PCI/MSIX interrupt domain

Parameters

struct pci_dev *dev

The PCI device to operate on

struct msi_map map

A struct msi_map describing the interrupt to free

Description

Undo an interrupt vector allocation. Does not disable MSI-X.

void pci_disable_msix(struct pci_dev *dev)

Disable MSI-X interrupt mode on device

Parameters

struct pci_dev *dev

the PCI device to operate on

Description

Legacy device driver API to disable MSI-X interrupt mode on device,free earlier-allocated interrupt vectors, and restore INTx.The PCI device Linux IRQ (dev->irq) is restored to its default pinassertion IRQ. This is the cleanup pair of pci_enable_msix_range().

NOTE

The newer pci_alloc_irq_vectors() / pci_free_irq_vectors() APIpair should, in general, be used instead.

int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags)

Allocate multiple device interrupt vectors

Parameters

struct pci_dev *dev

the PCI device to operate on

unsigned int min_vecs

minimum required number of vectors (must be >= 1)

unsigned int max_vecs

maximum desired number of vectors

unsigned int flags

One or more of:

  • PCI_IRQ_MSIX Allow trying MSI-X vector allocations

  • PCI_IRQ_MSI Allow trying MSI vector allocations

  • PCI_IRQ_INTX Allow trying INTx interrupts, if andonly if min_vecs == 1

  • PCI_IRQ_AFFINITY Auto-manage IRQs affinity by spreadingthe vectors around available CPUs

Description

Allocate up to max_vecs interrupt vectors on device. MSI-X irqvector allocation has a higher precedence over plain MSI, which has ahigher precedence over legacy INTx emulation.

Upon a successful allocation, the caller should use pci_irq_vector()to get the Linux IRQ number to be passed to request_threaded_irq().The driver must call pci_free_irq_vectors() on cleanup.

Return

number of allocated vectors (which might be smaller thanmax_vecs), -ENOSPC if less than min_vecs interrupt vectors areavailable, other errnos otherwise.

int pci_alloc_irq_vectors_affinity(struct pci_dev *dev, unsigned int min_vecs, unsigned int max_vecs, unsigned int flags, struct irq_affinity *affd)

Allocate multiple device interrupt vectors with affinity requirements

Parameters

struct pci_dev *dev

the PCI device to operate on

unsigned int min_vecs

minimum required number of vectors (must be >= 1)

unsigned int max_vecs

maximum desired number of vectors

unsigned int flags

allocation flags, as in pci_alloc_irq_vectors()

struct irq_affinity *affd

affinity requirements (can be NULL).

Description

Same as pci_alloc_irq_vectors(), but with the extra affd parameter.Check that function docs, and struct irq_affinity, for more details.

int pci_irq_vector(struct pci_dev *dev, unsigned int nr)

Get Linux IRQ number of a device interrupt vector

Parameters

struct pci_dev *dev

the PCI device to operate on

unsigned int nr

device-relative interrupt vector index (0-based); has differentmeanings, depending on interrupt mode:

  • MSI-X the index in the MSI-X vector table

  • MSI the index of the enabled MSI vectors

  • INTx must be 0

Return

the Linux IRQ number, or -EINVAL if nr is out of range

const struct cpumask *pci_irq_get_affinity(struct pci_dev *dev, int nr)

Get a device interrupt vector affinity

Parameters

struct pci_dev *dev

the PCI device to operate on

int nr

device-relative interrupt vector index (0-based); has differentmeanings, depending on interrupt mode:

  • MSI-X the index in the MSI-X vector table

  • MSI the index of the enabled MSI vectors

  • INTx must be 0

Return

MSI/MSI-X vector affinity, NULL if nr is out of range or ifthe MSI(-X) vector was allocated without explicit affinityrequirements (e.g., by pci_enable_msi(), pci_enable_msix_range(), orpci_alloc_irq_vectors() without the PCI_IRQ_AFFINITY flag). Return ageneric set of CPU IDs representing all possible CPUs availableduring system boot if the device is in legacy INTx mode.

void pci_free_irq_vectors(struct pci_dev *dev)

Free previously allocated IRQs for a device

Parameters

struct pci_dev *dev

the PCI device to operate on

Description

Undo the interrupt vector allocations and possible device MSI/MSI-Xenablement earlier done through pci_alloc_irq_vectors_affinity() orpci_alloc_irq_vectors().

void pci_restore_msi_state(struct pci_dev *dev)

Restore cached MSI(-X) state on device

Parameters

struct pci_dev *dev

the PCI device to operate on

Description

Write the Linux-cached MSI(-X) state back on device. This istypically useful upon system resume, or after an error-recovery PCIadapter reset.

int pci_msi_enabled(void)

Are MSI(-X) interrupts enabled system-wide?

Parameters

void

no arguments

Return

true if MSI has not been globally disabled through ACPI FADT,PCI bridge quirks, or the “pci=nomsi” kernel command-line option.

4. The MSI Driver Guide HOWTO — The Linux Kernel  documentation (2024)

References

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Edwin Metz

Last Updated:

Views: 5950

Rating: 4.8 / 5 (58 voted)

Reviews: 81% of readers found this page helpful

Author information

Name: Edwin Metz

Birthday: 1997-04-16

Address: 51593 Leanne Light, Kuphalmouth, DE 50012-5183

Phone: +639107620957

Job: Corporate Banking Technician

Hobby: Reading, scrapbook, role-playing games, Fishing, Fishing, Scuba diving, Beekeeping

Introduction: My name is Edwin Metz, I am a fair, energetic, helpful, brave, outstanding, nice, helpful person who loves writing and wants to share my knowledge and understanding with you.