Documentation/PCI/msi-howto.rst

1 .. SPDX-License-Identifier: GPL-2.0
16 the advantages of using MSI over traditional interrupt mechanisms, how
17 to change your driver to use MSI or MSI-X and some basic diagnostics to
24 A Message Signaled Interrupt is a write from the device to a special
25 address which causes an interrupt to be received by the CPU.
28 in PCI 3.0 to allow each interrupt to be masked individually.  The MSI-X
32 Devices may support both MSI and MSI-X, but only one can be enabled at
40 traditional pin-based interrupts.
42 Pin-based PCI interrupts are often shared amongst several devices.
43 To support this, the kernel must call each interrupt handler associated
44 with an interrupt, which leads to reduced performance for the system as
47 When a device writes data to memory, then raises a pin-based interrupt,
48 it is possible that the interrupt may arrive before all the data has
49 arrived in memory (this becomes more likely with devices behind PCI-PCI
51 the interrupt handler must read a register on the device which raised
52 the interrupt.  PCI transaction ordering rules require that all the data
54 Using MSIs avoids this problem as the interrupt-generating write cannot
55 pass the data writes, so by the time the interrupt is raised, the driver
58 PCI devices can only support a single pin-based interrupt per function.
60 occurred, slowing down interrupt handling for the common case.  With
61 MSIs, a device can support more interrupts, allowing each interrupt
63 infrequent conditions (such as errors) their own interrupt which allows
64 the driver to handle the normal interrupt handling path more efficiently.
65 Other possible designs include giving one interrupt to each packet queue
72 PCI devices are initialised to use pin-based interrupts.  The device
73 driver has to set up the device to use MSI or MSI-X.  Not all machines
75 will simply fail and the device will continue to use pin-based interrupts.
78 -------------------------------
80 To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
87 ---------
93 To automatically use MSI or MSI-X interrupt vectors, use the following
99 which allocates up to max_vecs interrupt vectors for a PCI device.  It
102 min_vecs argument set to this limit, and the PCI core will return -ENOSPC
105 The flags argument is used to specify which type of interrupt can be used
107 A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
108 any possible kind of interrupt.  If the PCI_IRQ_AFFINITY flag is set,
121 If a device supports both MSI-X and MSI capabilities, this API will use the
122 MSI-X facilities in preference to the MSI facilities.  MSI-X supports any
125 MSI interrupt vectors must be allocated consecutively, so the system might
126 not be able to allocate as many vectors for MSI as it could for MSI-X.  On
128 whereas MSI-X interrupts can all be targeted at different CPUs.
130 If a device supports neither MSI-X or MSI it will fall back to a single
133 The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
161 the driver can specify that only MSI or MSI-X is acceptable::
168 -----------
170 The following old APIs to enable and disable MSI or MSI-X interrupts should
179 Additionally there are APIs to provide the number of supported MSI or MSI-X
184 pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
187 ------------------------------
192 Most device drivers have a per-device spinlock which is taken in the
193 interrupt handler.  With pin-based interrupts or a single MSI, it is not
194 necessary to disable interrupts (Linux guarantees the same interrupt will
195 not be re-entered).  If a device uses multiple interrupts, the driver
197 a different interrupt, the driver will deadlock trying to recursively
200 and acquire the lock (see Documentation/kernel-hacking/locking.rst).
202 How to tell whether MSI/MSI-X is enabled on a device
203 ----------------------------------------------------
205 Using 'lspci -v' (as root) may show some devices with "MSI", "Message
206 Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
208 or "-" (disabled).
222 -----------------------
233 in your best interests to report the problem to linux-pci@vger.kernel.org
234 including a full 'lspci -v' so we can add the quirks to the kernel.
237 -----------------------------
256 done with caution as it could break interrupt handling for all devices
259 Again, please notify linux-pci@vger.kernel.org of any bridges that need
263 ---------------------------------
272 -----------------------------------------
280 Then, 'lspci -t' gives the list of bridges above a device. Reading
290 List of device drivers MSI(-X) APIs
296 .. kernel-doc:: drivers/pci/msi/api.c