Documentation/PCI/msi-howto.rst

1 .. SPDX-License-Identifier: GPL-2.0
5 The MSI Driver Guide HOWTO
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
27 The MSI capability was first specified in PCI 2.2 and was later enhanced
28 in PCI 3.0 to allow each interrupt to be masked individually.  The MSI-X
30 per device than MSI and allows interrupts to be independently configured.
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.
47 When a device writes data to memory, then raises a pin-based interrupt,
49 arrived in memory (this becomes more likely with devices behind PCI-PCI
54 Using MSIs avoids this problem as the interrupt-generating write cannot
58 PCI devices can only support a single pin-based interrupt per function.
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
86 Using MSI
87 ---------
90 simply has to request that the PCI layer set up the MSI capability for this
93 To automatically use MSI or MSI-X interrupt vectors, use the following
102 min_vecs argument set to this limit, and the PCI core will return -ENOSPC
107 A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
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
123 number of interrupts between 1 and 2048.  In contrast, MSI is restricted to
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
127 some platforms, MSI interrupts must all be targeted at the same set of CPUs
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
143 If a driver is unable or unwilling to deal with a variable number of MSI
153 the single MSI mode for a device.  It could be done by passing two 1s as
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
195 not be re-entered).  If a device uses multiple interrupts, the driver
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).
211 MSI quirks
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 -----------------------------
259 Again, please notify linux-pci@vger.kernel.org of any bridges that need
263 ---------------------------------
265 Some devices are known to have faulty MSI implementations.  Usually this
268 of MSI.  While this is a convenient workaround for the driver author,
272 -----------------------------------------
280 Then, 'lspci -t' gives the list of bridges above a device. Reading
290 List of device drivers MSI(-X) APIs
293 The PCI/MSI subsystem has a dedicated C file for its exported device driver
294 APIs — `drivers/pci/msi/api.c`. The following functions are exported:
296 .. kernel-doc:: drivers/pci/msi/api.c