Documentation/PCI/MSI-HOWTO.txt

   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 should normally be set to 0, but can be used to pass the
  98 PCI_IRQ_NOMSI and PCI_IRQ_NOMSIX flag in case a device claims to support
  99 MSI or MSI-X, but the support is broken, or to pass PCI_IRQ_NOLEGACY in
 100 case the device does not support legacy interrupt lines.
 101
 102 By default this function will spread the interrupts around the available
 103 CPUs, but this feature can be disabled by passing the PCI_IRQ_NOAFFINITY
 104 flag.
 105
 106 To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
 107 vectors, use the following function:
 108
 109   int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
 110
 111 Any allocated resources should be freed before removing the device using
 112 the following function:
 113
 114   void pci_free_irq_vectors(struct pci_dev *dev);
 115
 116 If a device supports both MSI-X and MSI capabilities, this API will use the
 117 MSI-X facilities in preference to the MSI facilities.  MSI-X supports any
 118 number of interrupts between 1 and 2048.  In contrast, MSI is restricted to
 119 a maximum of 32 interrupts (and must be a power of two).  In addition, the
 120 MSI interrupt vectors must be allocated consecutively, so the system might
 121 not be able to allocate as many vectors for MSI as it could for MSI-X.  On
 122 some platforms, MSI interrupts must all be targeted at the same set of CPUs
 123 whereas MSI-X interrupts can all be targeted at different CPUs.
 124
 125 If a device supports neither MSI-X or MSI it will fall back to a single
 126 legacy IRQ vector.
 127
 128 The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
 129 as possible, likely up to the limit supported by the device.  If nvec is
 130 larger than the number supported by the device it will automatically be
 131 capped to the supported limit, so there is no need to query the number of
 132 vectors supported beforehand:
 133
 134         nvec = pci_alloc_irq_vectors(pdev, 1, nvec, 0);
 135         if (nvec < 0)
 136                 goto out_err;
 137
 138 If a driver is unable or unwilling to deal with a variable number of MSI
 139 interrupts it can request a particular number of interrupts by passing that
 140 number to pci_alloc_irq_vectors() function as both 'min_vecs' and
 141 'max_vecs' parameters:
 142
 143         ret = pci_alloc_irq_vectors(pdev, nvec, nvec, 0);
 144         if (ret < 0)
 145                 goto out_err;
 146
 147 The most notorious example of the request type described above is enabling
 148 the single MSI mode for a device.  It could be done by passing two 1s as
 149 'min_vecs' and 'max_vecs':
 150
 151         ret = pci_alloc_irq_vectors(pdev, 1, 1, 0);
 152         if (ret < 0)
 153                 goto out_err;
 154
 155 Some devices might not support using legacy line interrupts, in which case
 156 the PCI_IRQ_NOLEGACY flag can be used to fail the request if the platform
 157 can't provide MSI or MSI-X interrupts:
 158
 159         nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_NOLEGACY);
 160         if (nvec < 0)
 161                 goto out_err;
 162
 163 4.3 Legacy APIs
 164
 165 The following old APIs to enable and disable MSI or MSI-X interrupts should
 166 not be used in new code:
 167
 168   pci_enable_msi()              /* deprecated */
 169   pci_enable_msi_range()        /* deprecated */
 170   pci_enable_msi_exact()        /* deprecated */
 171   pci_disable_msi()             /* deprecated */
 172   pci_enable_msix_range()       /* deprecated */
 173   pci_enable_msix_exact()       /* deprecated */
 174   pci_disable_msix()            /* deprecated */
 175
 176 Additionally there are APIs to provide the number of supported MSI or MSI-X
 177 vectors: pci_msi_vec_count() and pci_msix_vec_count().  In general these
 178 should be avoided in favor of letting pci_alloc_irq_vectors() cap the
 179 number of vectors.  If you have a legitimate special use case for the count
 180 of vectors we might have to revisit that decision and add a
 181 pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
 182
 183 4.4 Considerations when using MSIs
 184
 185 4.4.1 Spinlocks
 186
 187 Most device drivers have a per-device spinlock which is taken in the
 188 interrupt handler.  With pin-based interrupts or a single MSI, it is not
 189 necessary to disable interrupts (Linux guarantees the same interrupt will
 190 not be re-entered).  If a device uses multiple interrupts, the driver
 191 must disable interrupts while the lock is held.  If the device sends
 192 a different interrupt, the driver will deadlock trying to recursively
 193 acquire the spinlock.  Such deadlocks can be avoided by using
 194 spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
 195 and acquire the lock (see Documentation/DocBook/kernel-locking).
 196
 197 4.5 How to tell whether MSI/MSI-X is enabled on a device
 198
 199 Using 'lspci -v' (as root) may show some devices with "MSI", "Message
 200 Signalled Interrupts" or "MSI-X" capabilities.  Each of these capabilities
 201 has an 'Enable' flag which is followed with either "+" (enabled)
 202 or "-" (disabled).
 203
 204
 205 5. MSI quirks
 206
 207 Several PCI chipsets or devices are known not to support MSIs.
 208 The PCI stack provides three ways to disable MSIs:
 209
 210 1. globally
 211 2. on all devices behind a specific bridge
 212 3. on a single device
 213
 214 5.1. Disabling MSIs globally
 215
 216 Some host chipsets simply don't support MSIs properly.  If we're
 217 lucky, the manufacturer knows this and has indicated it in the ACPI
 218 FADT table.  In this case, Linux automatically disables MSIs.
 219 Some boards don't include this information in the table and so we have
 220 to detect them ourselves.  The complete list of these is found near the
 221 quirk_disable_all_msi() function in drivers/pci/quirks.c.
 222
 223 If you have a board which has problems with MSIs, you can pass pci=nomsi
 224 on the kernel command line to disable MSIs on all devices.  It would be
 225 in your best interests to report the problem to linux-pci@vger.kernel.org
 226 including a full 'lspci -v' so we can add the quirks to the kernel.
 227
 228 5.2. Disabling MSIs below a bridge
 229
 230 Some PCI bridges are not able to route MSIs between busses properly.
 231 In this case, MSIs must be disabled on all devices behind the bridge.
 232
 233 Some bridges allow you to enable MSIs by changing some bits in their
 234 PCI configuration space (especially the Hypertransport chipsets such
 235 as the nVidia nForce and Serverworks HT2000).  As with host chipsets,
 236 Linux mostly knows about them and automatically enables MSIs if it can.
 237 If you have a bridge unknown to Linux, you can enable
 238 MSIs in configuration space using whatever method you know works, then
 239 enable MSIs on that bridge by doing:
 240
 241        echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
 242
 243 where $bridge is the PCI address of the bridge you've enabled (eg
 244 0000:00:0e.0).
 245
 246 To disable MSIs, echo 0 instead of 1.  Changing this value should be
 247 done with caution as it could break interrupt handling for all devices
 248 below this bridge.
 249
 250 Again, please notify linux-pci@vger.kernel.org of any bridges that need
 251 special handling.
 252
 253 5.3. Disabling MSIs on a single device
 254
 255 Some devices are known to have faulty MSI implementations.  Usually this
 256 is handled in the individual device driver, but occasionally it's necessary
 257 to handle this with a quirk.  Some drivers have an option to disable use
 258 of MSI.  While this is a convenient workaround for the driver author,
 259 it is not good practice, and should not be emulated.
 260
 261 5.4. Finding why MSIs are disabled on a device
 262
 263 From the above three sections, you can see that there are many reasons
 264 why MSIs may not be enabled for a given device.  Your first step should
 265 be to examine your dmesg carefully to determine whether MSIs are enabled
 266 for your machine.  You should also check your .config to be sure you
 267 have enabled CONFIG_PCI_MSI.
 268
 269 Then, 'lspci -t' gives the list of bridges above a device.  Reading
 270 /sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1)
 271 or disabled (0).  If 0 is found in any of the msi_bus files belonging
 272 to bridges between the PCI root and the device, MSIs are disabled.
 273
 274 It is also worth checking the device driver to see whether it supports MSIs.
 275 For example, it may contain calls to pci_enable_msi_range() or
 276 pci_enable_msix_range().