Documentation/PCI/msi-howto.rst

1 .. SPDX-License-Identifier: GPL-2.0
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
29 capability was also introduced with PCI 3.0.  It supports more interrupts
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
52 the interrupt.  PCI transaction ordering rules require that all the data
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
87 ---------
89 Most of the hard work is done for the driver in the PCI layer.  The driver
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
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
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
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
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).
214 Several PCI chipsets or devices are known not to support MSIs.
215 The PCI stack provides three ways to disable MSIs:
222 -----------------------
229 quirk_disable_all_msi() function in drivers/pci/quirks.c.
231 If you have a board which has problems with MSIs, you can pass pci=nomsi
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 -----------------------------
239 Some PCI bridges are not able to route MSIs between buses properly.
243 PCI configuration space (especially the Hypertransport chipsets such
250        echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
252 where $bridge is the PCI address of the bridge you've enabled (eg
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
281 `/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1)
283 to bridges between the PCI root and the device, MSIs are disabled.
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