MSI-HOWTO.txt 11.5 KB
Newer Older
Linus Torvalds's avatar
Linus Torvalds committed
1 2 3 4 5 6
		The MSI Driver Guide HOWTO
	Tom L Nguyen tom.l.nguyen@intel.com
			10/03/2003
	Revised Feb 12, 2004 by Martine Silbermann
		email: Martine.Silbermann@hp.com
	Revised Jun 25, 2004 by Tom L Nguyen
Matthew Wilcox's avatar
Matthew Wilcox committed
7 8
	Revised Jul  9, 2008 by Matthew Wilcox <willy@linux.intel.com>
		Copyright 2003, 2008 Intel Corporation
Linus Torvalds's avatar
Linus Torvalds committed
9 10 11

1. About this guide

Matthew Wilcox's avatar
Matthew Wilcox committed
12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
This guide describes the basics of Message Signaled Interrupts (MSIs),
the advantages of using MSI over traditional interrupt mechanisms, how
to change your driver to use MSI or MSI-X and some basic diagnostics to
try if a device doesn't support MSIs.


2. What are MSIs?

A Message Signaled Interrupt is a write from the device to a special
address which causes an interrupt to be received by the CPU.

The MSI capability was first specified in PCI 2.2 and was later enhanced
in PCI 3.0 to allow each interrupt to be masked individually.  The MSI-X
capability was also introduced with PCI 3.0.  It supports more interrupts
per device than MSI and allows interrupts to be independently configured.

Devices may support both MSI and MSI-X, but only one can be enabled at
a time.


3. Why use MSIs?

There are three reasons why using MSIs can give an advantage over
traditional pin-based interrupts.

Pin-based PCI interrupts are often shared amongst several devices.
To support this, the kernel must call each interrupt handler associated
with an interrupt, which leads to reduced performance for the system as
a whole.  MSIs are never shared, so this problem cannot arise.

When a device writes data to memory, then raises a pin-based interrupt,
it is possible that the interrupt may arrive before all the data has
arrived in memory (this becomes more likely with devices behind PCI-PCI
bridges).  In order to ensure that all the data has arrived in memory,
the interrupt handler must read a register on the device which raised
the interrupt.  PCI transaction ordering rules require that all the data
48
arrive in memory before the value may be returned from the register.
Matthew Wilcox's avatar
Matthew Wilcox committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
Using MSIs avoids this problem as the interrupt-generating write cannot
pass the data writes, so by the time the interrupt is raised, the driver
knows that all the data has arrived in memory.

PCI devices can only support a single pin-based interrupt per function.
Often drivers have to query the device to find out what event has
occurred, slowing down interrupt handling for the common case.  With
MSIs, a device can support more interrupts, allowing each interrupt
to be specialised to a different purpose.  One possible design gives
infrequent conditions (such as errors) their own interrupt which allows
the driver to handle the normal interrupt handling path more efficiently.
Other possible designs include giving one interrupt to each packet queue
in a network card or each port in a storage controller.


4. How to use MSIs

PCI devices are initialised to use pin-based interrupts.  The device
driver has to set up the device to use MSI or MSI-X.  Not all machines
support MSIs correctly, and for those machines, the APIs described below
will simply fail and the device will continue to use pin-based interrupts.

4.1 Include kernel support for MSIs

To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
option enabled.  This option is only available on some architectures,
and it may depend on some other options also being set.  For example,
on x86, you must also enable X86_UP_APIC or SMP in order to see the
CONFIG_PCI_MSI option.

4.2 Using MSI

81 82
Most of the hard work is done for the driver in the PCI layer.  The driver
simply has to request that the PCI layer set up the MSI capability for this
Matthew Wilcox's avatar
Matthew Wilcox committed
83 84
device.

85 86
To automatically use MSI or MSI-X interrupt vectors, use the following
function:
87

88 89
  int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
		unsigned int max_vecs, unsigned int flags);
90

91 92 93 94 95
which allocates up to max_vecs interrupt vectors for a PCI device.  It
returns the number of vectors allocated or a negative error.  If the device
has a requirements for a minimum number of vectors the driver can pass a
min_vecs argument set to this limit, and the PCI core will return -ENOSPC
if it can't meet the minimum number of vectors.
96

97 98 99 100 101
The flags argument is used to specify which type of interrupt can be used
by the device and the driver (PCI_IRQ_LEGACY, PCI_IRQ_MSI, PCI_IRQ_MSIX).
A convenient short-hand (PCI_IRQ_ALL_TYPES) is also available to ask for
any possible kind of interrupt.  If the PCI_IRQ_AFFINITY flag is set,
pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
102

103 104
To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
vectors, use the following function:
Linus Torvalds's avatar
Linus Torvalds committed
105

106
  int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
Linus Torvalds's avatar
Linus Torvalds committed
107

108 109
Any allocated resources should be freed before removing the device using
the following function:
110

111
  void pci_free_irq_vectors(struct pci_dev *dev);
112

113 114 115 116 117 118 119 120
If a device supports both MSI-X and MSI capabilities, this API will use the
MSI-X facilities in preference to the MSI facilities.  MSI-X supports any
number of interrupts between 1 and 2048.  In contrast, MSI is restricted to
a maximum of 32 interrupts (and must be a power of two).  In addition, the
MSI interrupt vectors must be allocated consecutively, so the system might
not be able to allocate as many vectors for MSI as it could for MSI-X.  On
some platforms, MSI interrupts must all be targeted at the same set of CPUs
whereas MSI-X interrupts can all be targeted at different CPUs.
121

122 123
If a device supports neither MSI-X or MSI it will fall back to a single
legacy IRQ vector.
124

125 126 127 128 129
The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
as possible, likely up to the limit supported by the device.  If nvec is
larger than the number supported by the device it will automatically be
capped to the supported limit, so there is no need to query the number of
vectors supported beforehand:
130

131
	nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
132 133
	if (nvec < 0)
		goto out_err;
134 135

If a driver is unable or unwilling to deal with a variable number of MSI
136 137 138
interrupts it can request a particular number of interrupts by passing that
number to pci_alloc_irq_vectors() function as both 'min_vecs' and
'max_vecs' parameters:
Matthew Wilcox's avatar
Matthew Wilcox committed
139

140
	ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
141 142
	if (ret < 0)
		goto out_err;
143

144 145 146
The most notorious example of the request type described above is enabling
the single MSI mode for a device.  It could be done by passing two 1s as
'min_vecs' and 'max_vecs':
147

148
	ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
149 150
	if (ret < 0)
		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 157
	if (nvec < 0)
		goto out_err;
158

159
4.3 Legacy APIs
Matthew Wilcox's avatar
Matthew Wilcox committed
160

161 162
The following old APIs to enable and disable MSI or MSI-X interrupts should
not be used in new code:
Matthew Wilcox's avatar
Matthew Wilcox committed
163

164 165 166 167 168 169 170
  pci_enable_msi()		/* deprecated */
  pci_enable_msi_range()	/* deprecated */
  pci_enable_msi_exact()	/* deprecated */
  pci_disable_msi()		/* deprecated */
  pci_enable_msix_range()	/* deprecated */
  pci_enable_msix_exact()	/* deprecated */
  pci_disable_msix()		/* deprecated */
Matthew Wilcox's avatar
Matthew Wilcox committed
171

172 173 174 175 176 177
Additionally there are APIs to provide the number of supported MSI or MSI-X
vectors: pci_msi_vec_count() and pci_msix_vec_count().  In general these
should be avoided in favor of letting pci_alloc_irq_vectors() cap the
number of vectors.  If you have a legitimate special use case for the count
of vectors we might have to revisit that decision and add a
pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
Matthew Wilcox's avatar
Matthew Wilcox committed
178

179
4.4 Considerations when using MSIs
Matthew Wilcox's avatar
Matthew Wilcox committed
180

181
4.4.1 Spinlocks
Matthew Wilcox's avatar
Matthew Wilcox committed
182 183 184 185 186 187 188

Most device drivers have a per-device spinlock which is taken in the
interrupt handler.  With pin-based interrupts or a single MSI, it is not
necessary to disable interrupts (Linux guarantees the same interrupt will
not be re-entered).  If a device uses multiple interrupts, the driver
must disable interrupts while the lock is held.  If the device sends
a different interrupt, the driver will deadlock trying to recursively
189 190 191
acquire the spinlock.  Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
and acquire the lock (see Documentation/DocBook/kernel-locking).
Matthew Wilcox's avatar
Matthew Wilcox committed
192

193
4.5 How to tell whether MSI/MSI-X is enabled on a device
Matthew Wilcox's avatar
Matthew Wilcox committed
194 195 196

Using 'lspci -v' (as root) may show some devices with "MSI", "Message
Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
197
has an 'Enable' flag which is followed with either "+" (enabled)
Matthew Wilcox's avatar
Matthew Wilcox committed
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213
or "-" (disabled).


5. MSI quirks

Several PCI chipsets or devices are known not to support MSIs.
The PCI stack provides three ways to disable MSIs:

1. globally
2. on all devices behind a specific bridge
3. on a single device

5.1. Disabling MSIs globally

Some host chipsets simply don't support MSIs properly.  If we're
lucky, the manufacturer knows this and has indicated it in the ACPI
214
FADT table.  In this case, Linux automatically disables MSIs.
Matthew Wilcox's avatar
Matthew Wilcox committed
215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232
Some boards don't include this information in the table and so we have
to detect them ourselves.  The complete list of these is found near the
quirk_disable_all_msi() function in drivers/pci/quirks.c.

If you have a board which has problems with MSIs, you can pass pci=nomsi
on the kernel command line to disable MSIs on all devices.  It would be
in your best interests to report the problem to linux-pci@vger.kernel.org
including a full 'lspci -v' so we can add the quirks to the kernel.

5.2. Disabling MSIs below a bridge

Some PCI bridges are not able to route MSIs between busses properly.
In this case, MSIs must be disabled on all devices behind the bridge.

Some bridges allow you to enable MSIs by changing some bits in their
PCI configuration space (especially the Hypertransport chipsets such
as the nVidia nForce and Serverworks HT2000).  As with host chipsets,
Linux mostly knows about them and automatically enables MSIs if it can.
233
If you have a bridge unknown to Linux, you can enable
Matthew Wilcox's avatar
Matthew Wilcox committed
234 235 236 237 238 239 240 241 242
MSIs in configuration space using whatever method you know works, then
enable MSIs on that bridge by doing:

       echo 1 > /sys/bus/pci/devices/$bridge/msi_bus

where $bridge is the PCI address of the bridge you've enabled (eg
0000:00:0e.0).

To disable MSIs, echo 0 instead of 1.  Changing this value should be
243
done with caution as it could break interrupt handling for all devices
Matthew Wilcox's avatar
Matthew Wilcox committed
244 245 246 247 248 249 250 251
below this bridge.

Again, please notify linux-pci@vger.kernel.org of any bridges that need
special handling.

5.3. Disabling MSIs on a single device

Some devices are known to have faulty MSI implementations.  Usually this
252
is handled in the individual device driver, but occasionally it's necessary
Matthew Wilcox's avatar
Matthew Wilcox committed
253 254
to handle this with a quirk.  Some drivers have an option to disable use
of MSI.  While this is a convenient workaround for the driver author,
255
it is not good practice, and should not be emulated.
Matthew Wilcox's avatar
Matthew Wilcox committed
256 257 258 259 260 261 262 263 264 265

5.4. Finding why MSIs are disabled on a device

From the above three sections, you can see that there are many reasons
why MSIs may not be enabled for a given device.  Your first step should
be to examine your dmesg carefully to determine whether MSIs are enabled
for your machine.  You should also check your .config to be sure you
have enabled CONFIG_PCI_MSI.

Then, 'lspci -t' gives the list of bridges above a device.  Reading
266
/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)
Matthew Wilcox's avatar
Matthew Wilcox committed
267 268 269 270
or disabled (0).  If 0 is found in any of the msi_bus files belonging
to bridges between the PCI root and the device, MSIs are disabled.

It is also worth checking the device driver to see whether it supports MSIs.
271 272
For example, it may contain calls to pci_enable_msi_range() or
pci_enable_msix_range().