]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
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 | |
c41ade2e MW |
7 | Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com> |
8 | Copyright 2003, 2008 Intel Corporation | |
1da177e4 LT |
9 | |
10 | 1. About this guide | |
11 | ||
c41ade2e MW |
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 | |
891f6925 | 48 | arrive in memory before the value may be returned from the register. |
c41ade2e MW |
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. It simply | |
82 | has to request that the PCI layer set up the MSI capability for this | |
83 | device. | |
84 | ||
85 | 4.2.1 pci_enable_msi | |
1da177e4 LT |
86 | |
87 | int pci_enable_msi(struct pci_dev *dev) | |
88 | ||
4979de6e MW |
89 | A successful call allocates ONE interrupt to the device, regardless |
90 | of how many MSIs the device supports. The device is switched from | |
c41ade2e | 91 | pin-based interrupt mode to MSI mode. The dev->irq number is changed |
4979de6e MW |
92 | to a new number which represents the message signaled interrupt; |
93 | consequently, this function should be called before the driver calls | |
94 | request_irq(), because an MSI is delivered via a vector that is | |
95 | different from the vector of a pin-based interrupt. | |
1da177e4 | 96 | |
1c8d7b0a MW |
97 | 4.2.2 pci_enable_msi_block |
98 | ||
99 | int pci_enable_msi_block(struct pci_dev *dev, int count) | |
100 | ||
101 | This variation on the above call allows a device driver to request multiple | |
102 | MSIs. The MSI specification only allows interrupts to be allocated in | |
103 | powers of two, up to a maximum of 2^5 (32). | |
104 | ||
105 | If this function returns 0, it has succeeded in allocating at least as many | |
106 | interrupts as the driver requested (it may have allocated more in order | |
107 | to satisfy the power-of-two requirement). In this case, the function | |
108 | enables MSI on this device and updates dev->irq to be the lowest of | |
109 | the new interrupts assigned to it. The other interrupts assigned to | |
110 | the device are in the range dev->irq to dev->irq + count - 1. | |
111 | ||
112 | If this function returns a negative number, it indicates an error and | |
113 | the driver should not attempt to request any more MSI interrupts for | |
4979de6e MW |
114 | this device. If this function returns a positive number, it is |
115 | less than 'count' and indicates the number of interrupts that could have | |
116 | been allocated. In neither case is the irq value updated or the device | |
117 | switched into MSI mode. | |
1c8d7b0a MW |
118 | |
119 | The device driver must decide what action to take if | |
a2d4d501 | 120 | pci_enable_msi_block() returns a value less than the number requested. |
1d15afcc MW |
121 | For instance, the driver could still make use of fewer interrupts; |
122 | in this case the driver should call pci_enable_msi_block() | |
1c8d7b0a MW |
123 | again. Note that it is not guaranteed to succeed, even when the |
124 | 'count' has been reduced to the value returned from a previous call to | |
125 | pci_enable_msi_block(). This is because there are multiple constraints | |
126 | on the number of vectors that can be allocated; pci_enable_msi_block() | |
4979de6e | 127 | returns as soon as it finds any constraint that doesn't allow the |
1c8d7b0a MW |
128 | call to succeed. |
129 | ||
08261d87 AG |
130 | 4.2.3 pci_enable_msi_block_auto |
131 | ||
52179dc9 | 132 | int pci_enable_msi_block_auto(struct pci_dev *dev, int *count) |
08261d87 AG |
133 | |
134 | This variation on pci_enable_msi() call allows a device driver to request | |
135 | the maximum possible number of MSIs. The MSI specification only allows | |
136 | interrupts to be allocated in powers of two, up to a maximum of 2^5 (32). | |
137 | ||
138 | If this function returns a positive number, it indicates that it has | |
139 | succeeded and the returned value is the number of allocated interrupts. In | |
140 | this case, the function enables MSI on this device and updates dev->irq to | |
141 | be the lowest of the new interrupts assigned to it. The other interrupts | |
142 | assigned to the device are in the range dev->irq to dev->irq + returned | |
143 | value - 1. | |
144 | ||
145 | If this function returns a negative number, it indicates an error and | |
146 | the driver should not attempt to request any more MSI interrupts for | |
147 | this device. | |
148 | ||
149 | If the device driver needs to know the number of interrupts the device | |
150 | supports it can pass the pointer count where that number is stored. The | |
151 | device driver must decide what action to take if pci_enable_msi_block_auto() | |
152 | succeeds, but returns a value less than the number of interrupts supported. | |
153 | If the device driver does not need to know the number of interrupts | |
154 | supported, it can set the pointer count to NULL. | |
155 | ||
156 | 4.2.4 pci_disable_msi | |
1da177e4 LT |
157 | |
158 | void pci_disable_msi(struct pci_dev *dev) | |
159 | ||
1c8d7b0a | 160 | This function should be used to undo the effect of pci_enable_msi() or |
08261d87 AG |
161 | pci_enable_msi_block() or pci_enable_msi_block_auto(). Calling it restores |
162 | dev->irq to the pin-based interrupt number and frees the previously | |
163 | allocated message signaled interrupt(s). The interrupt may subsequently be | |
164 | assigned to another device, so drivers should not cache the value of | |
165 | dev->irq. | |
1da177e4 | 166 | |
263d8d57 MW |
167 | Before calling this function, a device driver must always call free_irq() |
168 | on any interrupt for which it previously called request_irq(). | |
4979de6e MW |
169 | Failure to do so results in a BUG_ON(), leaving the device with |
170 | MSI enabled and thus leaking its vector. | |
1da177e4 | 171 | |
c41ade2e | 172 | 4.3 Using MSI-X |
1da177e4 | 173 | |
c41ade2e MW |
174 | The MSI-X capability is much more flexible than the MSI capability. |
175 | It supports up to 2048 interrupts, each of which can be controlled | |
176 | independently. To support this flexibility, drivers must use an array of | |
177 | `struct msix_entry': | |
1da177e4 LT |
178 | |
179 | struct msix_entry { | |
180 | u16 vector; /* kernel uses to write alloc vector */ | |
181 | u16 entry; /* driver uses to specify entry */ | |
182 | }; | |
183 | ||
c41ade2e | 184 | This allows for the device to use these interrupts in a sparse fashion; |
e4439236 | 185 | for example, it could use interrupts 3 and 1027 and yet allocate only a |
c41ade2e | 186 | two-element array. The driver is expected to fill in the 'entry' value |
e4439236 MW |
187 | in each element of the array to indicate for which entries the kernel |
188 | should assign interrupts; it is invalid to fill in two entries with the | |
c41ade2e MW |
189 | same number. |
190 | ||
191 | 4.3.1 pci_enable_msix | |
192 | ||
193 | int pci_enable_msix(struct pci_dev *dev, struct msix_entry *entries, int nvec) | |
194 | ||
195 | Calling this function asks the PCI subsystem to allocate 'nvec' MSIs. | |
196 | The 'entries' argument is a pointer to an array of msix_entry structs | |
197 | which should be at least 'nvec' entries in size. On success, the | |
4979de6e MW |
198 | device is switched into MSI-X mode and the function returns 0. |
199 | The 'vector' member in each entry is populated with the interrupt number; | |
200 | the driver should then call request_irq() for each 'vector' that it | |
6457d9b3 MW |
201 | decides to use. The device driver is responsible for keeping track of the |
202 | interrupts assigned to the MSI-X vectors so it can free them again later. | |
c41ade2e MW |
203 | |
204 | If this function returns a negative number, it indicates an error and | |
205 | the driver should not attempt to allocate any more MSI-X interrupts for | |
206 | this device. If it returns a positive number, it indicates the maximum | |
fafad5bf ME |
207 | number of interrupt vectors that could have been allocated. See example |
208 | below. | |
c41ade2e MW |
209 | |
210 | This function, in contrast with pci_enable_msi(), does not adjust | |
211 | dev->irq. The device will not generate interrupts for this interrupt | |
6457d9b3 | 212 | number once MSI-X is enabled. |
c41ade2e MW |
213 | |
214 | Device drivers should normally call this function once per device | |
215 | during the initialization phase. | |
216 | ||
5a84fc31 | 217 | It is ideal if drivers can cope with a variable number of MSI-X interrupts; |
fafad5bf | 218 | there are many reasons why the platform may not be able to provide the |
ed737c18 | 219 | exact number that a driver asks for. |
fafad5bf ME |
220 | |
221 | A request loop to achieve that might look like: | |
222 | ||
223 | static int foo_driver_enable_msix(struct foo_adapter *adapter, int nvec) | |
224 | { | |
225 | while (nvec >= FOO_DRIVER_MINIMUM_NVEC) { | |
226 | rc = pci_enable_msix(adapter->pdev, | |
227 | adapter->msix_entries, nvec); | |
228 | if (rc > 0) | |
229 | nvec = rc; | |
230 | else | |
231 | return rc; | |
232 | } | |
233 | ||
234 | return -ENOSPC; | |
235 | } | |
236 | ||
c41ade2e | 237 | 4.3.2 pci_disable_msix |
1da177e4 LT |
238 | |
239 | void pci_disable_msix(struct pci_dev *dev) | |
240 | ||
e6ffceb0 | 241 | This function should be used to undo the effect of pci_enable_msix(). It frees |
c41ade2e MW |
242 | the previously allocated message signaled interrupts. The interrupts may |
243 | subsequently be assigned to another device, so drivers should not cache | |
244 | the value of the 'vector' elements over a call to pci_disable_msix(). | |
245 | ||
263d8d57 MW |
246 | Before calling this function, a device driver must always call free_irq() |
247 | on any interrupt for which it previously called request_irq(). | |
4979de6e MW |
248 | Failure to do so results in a BUG_ON(), leaving the device with |
249 | MSI-X enabled and thus leaking its vector. | |
c41ade2e MW |
250 | |
251 | 4.3.3 The MSI-X Table | |
252 | ||
253 | The MSI-X capability specifies a BAR and offset within that BAR for the | |
254 | MSI-X Table. This address is mapped by the PCI subsystem, and should not | |
255 | be accessed directly by the device driver. If the driver wishes to | |
256 | mask or unmask an interrupt, it should call disable_irq() / enable_irq(). | |
257 | ||
258 | 4.4 Handling devices implementing both MSI and MSI-X capabilities | |
259 | ||
260 | If a device implements both MSI and MSI-X capabilities, it can | |
e14bd7e6 | 261 | run in either MSI mode or MSI-X mode, but not both simultaneously. |
c41ade2e MW |
262 | This is a requirement of the PCI spec, and it is enforced by the |
263 | PCI layer. Calling pci_enable_msi() when MSI-X is already enabled or | |
4979de6e | 264 | pci_enable_msix() when MSI is already enabled results in an error. |
c41ade2e MW |
265 | If a device driver wishes to switch between MSI and MSI-X at runtime, |
266 | it must first quiesce the device, then switch it back to pin-interrupt | |
267 | mode, before calling pci_enable_msi() or pci_enable_msix() and resuming | |
268 | operation. This is not expected to be a common operation but may be | |
269 | useful for debugging or testing during development. | |
270 | ||
271 | 4.5 Considerations when using MSIs | |
272 | ||
273 | 4.5.1 Choosing between MSI-X and MSI | |
274 | ||
275 | If your device supports both MSI-X and MSI capabilities, you should use | |
276 | the MSI-X facilities in preference to the MSI facilities. As mentioned | |
277 | above, MSI-X supports any number of interrupts between 1 and 2048. | |
278 | In constrast, MSI is restricted to a maximum of 32 interrupts (and | |
279 | must be a power of two). In addition, the MSI interrupt vectors must | |
952df55b | 280 | be allocated consecutively, so the system might not be able to allocate |
c41ade2e | 281 | as many vectors for MSI as it could for MSI-X. On some platforms, MSI |
25985edc LDM |
282 | interrupts must all be targeted at the same set of CPUs whereas MSI-X |
283 | interrupts can all be targeted at different CPUs. | |
c41ade2e MW |
284 | |
285 | 4.5.2 Spinlocks | |
286 | ||
287 | Most device drivers have a per-device spinlock which is taken in the | |
288 | interrupt handler. With pin-based interrupts or a single MSI, it is not | |
289 | necessary to disable interrupts (Linux guarantees the same interrupt will | |
290 | not be re-entered). If a device uses multiple interrupts, the driver | |
291 | must disable interrupts while the lock is held. If the device sends | |
292 | a different interrupt, the driver will deadlock trying to recursively | |
293 | acquire the spinlock. | |
294 | ||
295 | There are two solutions. The first is to take the lock with | |
296 | spin_lock_irqsave() or spin_lock_irq() (see | |
297 | Documentation/DocBook/kernel-locking). The second is to specify | |
298 | IRQF_DISABLED to request_irq() so that the kernel runs the entire | |
299 | interrupt routine with interrupts disabled. | |
300 | ||
301 | If your MSI interrupt routine does not hold the lock for the whole time | |
302 | it is running, the first solution may be best. The second solution is | |
303 | normally preferred as it avoids making two transitions from interrupt | |
304 | disabled to enabled and back again. | |
305 | ||
306 | 4.6 How to tell whether MSI/MSI-X is enabled on a device | |
307 | ||
308 | Using 'lspci -v' (as root) may show some devices with "MSI", "Message | |
309 | Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities | |
4979de6e | 310 | has an 'Enable' flag which is followed with either "+" (enabled) |
c41ade2e MW |
311 | or "-" (disabled). |
312 | ||
313 | ||
314 | 5. MSI quirks | |
315 | ||
316 | Several PCI chipsets or devices are known not to support MSIs. | |
317 | The PCI stack provides three ways to disable MSIs: | |
318 | ||
319 | 1. globally | |
320 | 2. on all devices behind a specific bridge | |
321 | 3. on a single device | |
322 | ||
323 | 5.1. Disabling MSIs globally | |
324 | ||
325 | Some host chipsets simply don't support MSIs properly. If we're | |
326 | lucky, the manufacturer knows this and has indicated it in the ACPI | |
4979de6e | 327 | FADT table. In this case, Linux automatically disables MSIs. |
c41ade2e MW |
328 | Some boards don't include this information in the table and so we have |
329 | to detect them ourselves. The complete list of these is found near the | |
330 | quirk_disable_all_msi() function in drivers/pci/quirks.c. | |
331 | ||
332 | If you have a board which has problems with MSIs, you can pass pci=nomsi | |
333 | on the kernel command line to disable MSIs on all devices. It would be | |
334 | in your best interests to report the problem to linux-pci@vger.kernel.org | |
335 | including a full 'lspci -v' so we can add the quirks to the kernel. | |
336 | ||
337 | 5.2. Disabling MSIs below a bridge | |
338 | ||
339 | Some PCI bridges are not able to route MSIs between busses properly. | |
340 | In this case, MSIs must be disabled on all devices behind the bridge. | |
341 | ||
342 | Some bridges allow you to enable MSIs by changing some bits in their | |
343 | PCI configuration space (especially the Hypertransport chipsets such | |
344 | as the nVidia nForce and Serverworks HT2000). As with host chipsets, | |
345 | Linux mostly knows about them and automatically enables MSIs if it can. | |
e6b85a1f | 346 | If you have a bridge unknown to Linux, you can enable |
c41ade2e MW |
347 | MSIs in configuration space using whatever method you know works, then |
348 | enable MSIs on that bridge by doing: | |
349 | ||
350 | echo 1 > /sys/bus/pci/devices/$bridge/msi_bus | |
351 | ||
352 | where $bridge is the PCI address of the bridge you've enabled (eg | |
353 | 0000:00:0e.0). | |
354 | ||
355 | To disable MSIs, echo 0 instead of 1. Changing this value should be | |
1b8386f6 | 356 | done with caution as it could break interrupt handling for all devices |
c41ade2e MW |
357 | below this bridge. |
358 | ||
359 | Again, please notify linux-pci@vger.kernel.org of any bridges that need | |
360 | special handling. | |
361 | ||
362 | 5.3. Disabling MSIs on a single device | |
363 | ||
364 | Some devices are known to have faulty MSI implementations. Usually this | |
c2b65e18 | 365 | is handled in the individual device driver, but occasionally it's necessary |
c41ade2e MW |
366 | to handle this with a quirk. Some drivers have an option to disable use |
367 | of MSI. While this is a convenient workaround for the driver author, | |
368 | it is not good practise, and should not be emulated. | |
369 | ||
370 | 5.4. Finding why MSIs are disabled on a device | |
371 | ||
372 | From the above three sections, you can see that there are many reasons | |
373 | why MSIs may not be enabled for a given device. Your first step should | |
374 | be to examine your dmesg carefully to determine whether MSIs are enabled | |
375 | for your machine. You should also check your .config to be sure you | |
376 | have enabled CONFIG_PCI_MSI. | |
377 | ||
378 | Then, 'lspci -t' gives the list of bridges above a device. Reading | |
798c794d | 379 | /sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) |
c41ade2e MW |
380 | or disabled (0). If 0 is found in any of the msi_bus files belonging |
381 | to bridges between the PCI root and the device, MSIs are disabled. | |
382 | ||
383 | It is also worth checking the device driver to see whether it supports MSIs. | |
384 | For example, it may contain calls to pci_enable_msi(), pci_enable_msix() or | |
385 | pci_enable_msi_block(). |