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