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