1.. SPDX-License-Identifier: GPL-2.0
2.. include:: <isonum.txt>
3
4==========================
5The MSI Driver Guide HOWTO
6==========================
7
8:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
9
10:Copyright: 2003, 2008 Intel Corporation
11
12About this guide
13================
14
15This guide describes the basics of Message Signaled Interrupts (MSIs),
16the advantages of using MSI over traditional interrupt mechanisms, how
17to change your driver to use MSI or MSI-X and some basic diagnostics to
18try if a device doesn't support MSIs.
19
20
21What are MSIs?
22==============
23
24A Message Signaled Interrupt is a write from the device to a special
25address which causes an interrupt to be received by the CPU.
26
27The MSI capability was first specified in PCI 2.2 and was later enhanced
28in PCI 3.0 to allow each interrupt to be masked individually.  The MSI-X
29capability was also introduced with PCI 3.0.  It supports more interrupts
30per device than MSI and allows interrupts to be independently configured.
31
32Devices may support both MSI and MSI-X, but only one can be enabled at
33a time.
34
35
36Why use MSIs?
37=============
38
39There are three reasons why using MSIs can give an advantage over
40traditional pin-based interrupts.
41
42Pin-based PCI interrupts are often shared amongst several devices.
43To support this, the kernel must call each interrupt handler associated
44with an interrupt, which leads to reduced performance for the system as
45a whole.  MSIs are never shared, so this problem cannot arise.
46
47When a device writes data to memory, then raises a pin-based interrupt,
48it is possible that the interrupt may arrive before all the data has
49arrived in memory (this becomes more likely with devices behind PCI-PCI
50bridges).  In order to ensure that all the data has arrived in memory,
51the interrupt handler must read a register on the device which raised
52the interrupt.  PCI transaction ordering rules require that all the data
53arrive in memory before the value may be returned from the register.
54Using MSIs avoids this problem as the interrupt-generating write cannot
55pass the data writes, so by the time the interrupt is raised, the driver
56knows that all the data has arrived in memory.
57
58PCI devices can only support a single pin-based interrupt per function.
59Often drivers have to query the device to find out what event has
60occurred, slowing down interrupt handling for the common case.  With
61MSIs, a device can support more interrupts, allowing each interrupt
62to be specialised to a different purpose.  One possible design gives
63infrequent conditions (such as errors) their own interrupt which allows
64the driver to handle the normal interrupt handling path more efficiently.
65Other possible designs include giving one interrupt to each packet queue
66in a network card or each port in a storage controller.
67
68
69How to use MSIs
70===============
71
72PCI devices are initialised to use pin-based interrupts.  The device
73driver has to set up the device to use MSI or MSI-X.  Not all machines
74support MSIs correctly, and for those machines, the APIs described below
75will simply fail and the device will continue to use pin-based interrupts.
76
77Include kernel support for MSIs
78-------------------------------
79
80To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
81option enabled.  This option is only available on some architectures,
82and it may depend on some other options also being set.  For example,
83on x86, you must also enable X86_UP_APIC or SMP in order to see the
84CONFIG_PCI_MSI option.
85
86Using MSI
87---------
88
89Most of the hard work is done for the driver in the PCI layer.  The driver
90simply has to request that the PCI layer set up the MSI capability for this
91device.
92
93To automatically use MSI or MSI-X interrupt vectors, use the following
94function::
95
96  int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
97		unsigned int max_vecs, unsigned int flags);
98
99which allocates up to max_vecs interrupt vectors for a PCI device.  It
100returns the number of vectors allocated or a negative error.  If the device
101has a requirements for a minimum number of vectors the driver can pass a
102min_vecs argument set to this limit, and the PCI core will return -ENOSPC
103if it can't meet the minimum number of vectors.
104
105The flags argument is used to specify which type of interrupt can be used
106by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
107A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
108any possible kind of interrupt.  If the PCI_IRQ_AFFINITY flag is set,
109pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
110
111To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
112vectors, use the following function::
113
114  int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
115
116Any allocated resources should be freed before removing the device using
117the following function::
118
119  void pci_free_irq_vectors(struct pci_dev *dev);
120
121If a device supports both MSI-X and MSI capabilities, this API will use the
122MSI-X facilities in preference to the MSI facilities.  MSI-X supports any
123number of interrupts between 1 and 2048.  In contrast, MSI is restricted to
124a maximum of 32 interrupts (and must be a power of two).  In addition, the
125MSI interrupt vectors must be allocated consecutively, so the system might
126not be able to allocate as many vectors for MSI as it could for MSI-X.  On
127some platforms, MSI interrupts must all be targeted at the same set of CPUs
128whereas MSI-X interrupts can all be targeted at different CPUs.
129
130If a device supports neither MSI-X or MSI it will fall back to a single
131legacy IRQ vector.
132
133The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
134as possible, likely up to the limit supported by the device.  If nvec is
135larger than the number supported by the device it will automatically be
136capped to the supported limit, so there is no need to query the number of
137vectors supported beforehand::
138
139	nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
140	if (nvec < 0)
141		goto out_err;
142
143If a driver is unable or unwilling to deal with a variable number of MSI
144interrupts it can request a particular number of interrupts by passing that
145number to pci_alloc_irq_vectors() function as both 'min_vecs' and
146'max_vecs' parameters::
147
148	ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
149	if (ret < 0)
150		goto out_err;
151
152The most notorious example of the request type described above is enabling
153the single MSI mode for a device.  It could be done by passing two 1s as
154'min_vecs' and 'max_vecs'::
155
156	ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
157	if (ret < 0)
158		goto out_err;
159
160Some devices might not support using legacy line interrupts, in which case
161the driver can specify that only MSI or MSI-X is acceptable::
162
163	nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
164	if (nvec < 0)
165		goto out_err;
166
167Legacy APIs
168-----------
169
170The following old APIs to enable and disable MSI or MSI-X interrupts should
171not be used in new code::
172
173  pci_enable_msi()		/* deprecated */
174  pci_disable_msi()		/* deprecated */
175  pci_enable_msix_range()	/* deprecated */
176  pci_enable_msix_exact()	/* deprecated */
177  pci_disable_msix()		/* deprecated */
178
179Additionally there are APIs to provide the number of supported MSI or MSI-X
180vectors: pci_msi_vec_count() and pci_msix_vec_count().  In general these
181should be avoided in favor of letting pci_alloc_irq_vectors() cap the
182number of vectors.  If you have a legitimate special use case for the count
183of vectors we might have to revisit that decision and add a
184pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
185
186Considerations when using MSIs
187------------------------------
188
189Spinlocks
190~~~~~~~~~
191
192Most device drivers have a per-device spinlock which is taken in the
193interrupt handler.  With pin-based interrupts or a single MSI, it is not
194necessary to disable interrupts (Linux guarantees the same interrupt will
195not be re-entered).  If a device uses multiple interrupts, the driver
196must disable interrupts while the lock is held.  If the device sends
197a different interrupt, the driver will deadlock trying to recursively
198acquire the spinlock.  Such deadlocks can be avoided by using
199spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
200and acquire the lock (see Documentation/kernel-hacking/locking.rst).
201
202How to tell whether MSI/MSI-X is enabled on a device
203----------------------------------------------------
204
205Using 'lspci -v' (as root) may show some devices with "MSI", "Message
206Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
207has an 'Enable' flag which is followed with either "+" (enabled)
208or "-" (disabled).
209
210
211MSI quirks
212==========
213
214Several PCI chipsets or devices are known not to support MSIs.
215The PCI stack provides three ways to disable MSIs:
216
2171. globally
2182. on all devices behind a specific bridge
2193. on a single device
220
221Disabling MSIs globally
222-----------------------
223
224Some host chipsets simply don't support MSIs properly.  If we're
225lucky, the manufacturer knows this and has indicated it in the ACPI
226FADT table.  In this case, Linux automatically disables MSIs.
227Some boards don't include this information in the table and so we have
228to detect them ourselves.  The complete list of these is found near the
229quirk_disable_all_msi() function in drivers/pci/quirks.c.
230
231If you have a board which has problems with MSIs, you can pass pci=nomsi
232on the kernel command line to disable MSIs on all devices.  It would be
233in your best interests to report the problem to linux-pci@vger.kernel.org
234including a full 'lspci -v' so we can add the quirks to the kernel.
235
236Disabling MSIs below a bridge
237-----------------------------
238
239Some PCI bridges are not able to route MSIs between busses properly.
240In this case, MSIs must be disabled on all devices behind the bridge.
241
242Some bridges allow you to enable MSIs by changing some bits in their
243PCI configuration space (especially the Hypertransport chipsets such
244as the nVidia nForce and Serverworks HT2000).  As with host chipsets,
245Linux mostly knows about them and automatically enables MSIs if it can.
246If you have a bridge unknown to Linux, you can enable
247MSIs in configuration space using whatever method you know works, then
248enable MSIs on that bridge by doing::
249
250       echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
251
252where $bridge is the PCI address of the bridge you've enabled (eg
2530000:00:0e.0).
254
255To disable MSIs, echo 0 instead of 1.  Changing this value should be
256done with caution as it could break interrupt handling for all devices
257below this bridge.
258
259Again, please notify linux-pci@vger.kernel.org of any bridges that need
260special handling.
261
262Disabling MSIs on a single device
263---------------------------------
264
265Some devices are known to have faulty MSI implementations.  Usually this
266is handled in the individual device driver, but occasionally it's necessary
267to handle this with a quirk.  Some drivers have an option to disable use
268of MSI.  While this is a convenient workaround for the driver author,
269it is not good practice, and should not be emulated.
270
271Finding why MSIs are disabled on a device
272-----------------------------------------
273
274From the above three sections, you can see that there are many reasons
275why MSIs may not be enabled for a given device.  Your first step should
276be to examine your dmesg carefully to determine whether MSIs are enabled
277for your machine.  You should also check your .config to be sure you
278have enabled CONFIG_PCI_MSI.
279
280Then, '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)
282or disabled (0).  If 0 is found in any of the msi_bus files belonging
283to bridges between the PCI root and the device, MSIs are disabled.
284
285It is also worth checking the device driver to see whether it supports MSIs.
286For example, it may contain calls to pci_alloc_irq_vectors() with the
287PCI_IRQ_MSI or PCI_IRQ_MSIX flags.
288
289
290List of device drivers MSI(-X) APIs
291===================================
292
293The PCI/MSI subystem has a dedicated C file for its exported device driver
294APIs — `drivers/pci/msi/api.c`. The following functions are exported:
295
296.. kernel-doc:: drivers/pci/msi/api.c
297   :export:
298