About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / PCI / MSI-HOWTO.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog