ia64/linux-2.6.18-xen.hg

annotate Documentation/MSI-HOWTO.txt @ 854:950b9eb27661

usbback: fix urb interval value for interrupt urbs.

Signed-off-by: Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com>
author Keir Fraser <keir.fraser@citrix.com>
date Mon Apr 06 13:51:20 2009 +0100 (2009-04-06)
parents 831230e53067
children
rev   line source
ian@0 1 The MSI Driver Guide HOWTO
ian@0 2 Tom L Nguyen tom.l.nguyen@intel.com
ian@0 3 10/03/2003
ian@0 4 Revised Feb 12, 2004 by Martine Silbermann
ian@0 5 email: Martine.Silbermann@hp.com
ian@0 6 Revised Jun 25, 2004 by Tom L Nguyen
ian@0 7
ian@0 8 1. About this guide
ian@0 9
ian@0 10 This guide describes the basics of Message Signaled Interrupts (MSI),
ian@0 11 the advantages of using MSI over traditional interrupt mechanisms,
ian@0 12 and how to enable your driver to use MSI or MSI-X. Also included is
ian@0 13 a Frequently Asked Questions (FAQ) section.
ian@0 14
ian@0 15 1.1 Terminology
ian@0 16
ian@0 17 PCI devices can be single-function or multi-function. In either case,
ian@0 18 when this text talks about enabling or disabling MSI on a "device
ian@0 19 function," it is referring to one specific PCI device and function and
ian@0 20 not to all functions on a PCI device (unless the PCI device has only
ian@0 21 one function).
ian@0 22
ian@0 23 2. Copyright 2003 Intel Corporation
ian@0 24
ian@0 25 3. What is MSI/MSI-X?
ian@0 26
ian@0 27 Message Signaled Interrupt (MSI), as described in the PCI Local Bus
ian@0 28 Specification Revision 2.3 or later, is an optional feature, and a
ian@0 29 required feature for PCI Express devices. MSI enables a device function
ian@0 30 to request service by sending an Inbound Memory Write on its PCI bus to
ian@0 31 the FSB as a Message Signal Interrupt transaction. Because MSI is
ian@0 32 generated in the form of a Memory Write, all transaction conditions,
ian@0 33 such as a Retry, Master-Abort, Target-Abort or normal completion, are
ian@0 34 supported.
ian@0 35
ian@0 36 A PCI device that supports MSI must also support pin IRQ assertion
ian@0 37 interrupt mechanism to provide backward compatibility for systems that
ian@0 38 do not support MSI. In systems which support MSI, the bus driver is
ian@0 39 responsible for initializing the message address and message data of
ian@0 40 the device function's MSI/MSI-X capability structure during device
ian@0 41 initial configuration.
ian@0 42
ian@0 43 An MSI capable device function indicates MSI support by implementing
ian@0 44 the MSI/MSI-X capability structure in its PCI capability list. The
ian@0 45 device function may implement both the MSI capability structure and
ian@0 46 the MSI-X capability structure; however, the bus driver should not
ian@0 47 enable both.
ian@0 48
ian@0 49 The MSI capability structure contains Message Control register,
ian@0 50 Message Address register and Message Data register. These registers
ian@0 51 provide the bus driver control over MSI. The Message Control register
ian@0 52 indicates the MSI capability supported by the device. The Message
ian@0 53 Address register specifies the target address and the Message Data
ian@0 54 register specifies the characteristics of the message. To request
ian@0 55 service, the device function writes the content of the Message Data
ian@0 56 register to the target address. The device and its software driver
ian@0 57 are prohibited from writing to these registers.
ian@0 58
ian@0 59 The MSI-X capability structure is an optional extension to MSI. It
ian@0 60 uses an independent and separate capability structure. There are
ian@0 61 some key advantages to implementing the MSI-X capability structure
ian@0 62 over the MSI capability structure as described below.
ian@0 63
ian@0 64 - Support a larger maximum number of vectors per function.
ian@0 65
ian@0 66 - Provide the ability for system software to configure
ian@0 67 each vector with an independent message address and message
ian@0 68 data, specified by a table that resides in Memory Space.
ian@0 69
ian@0 70 - MSI and MSI-X both support per-vector masking. Per-vector
ian@0 71 masking is an optional extension of MSI but a required
ian@0 72 feature for MSI-X. Per-vector masking provides the kernel the
ian@0 73 ability to mask/unmask a single MSI while running its
ian@0 74 interrupt service routine. If per-vector masking is
ian@0 75 not supported, then the device driver should provide the
ian@0 76 hardware/software synchronization to ensure that the device
ian@0 77 generates MSI when the driver wants it to do so.
ian@0 78
ian@0 79 4. Why use MSI?
ian@0 80
ian@0 81 As a benefit to the simplification of board design, MSI allows board
ian@0 82 designers to remove out-of-band interrupt routing. MSI is another
ian@0 83 step towards a legacy-free environment.
ian@0 84
ian@0 85 Due to increasing pressure on chipset and processor packages to
ian@0 86 reduce pin count, the need for interrupt pins is expected to
ian@0 87 diminish over time. Devices, due to pin constraints, may implement
ian@0 88 messages to increase performance.
ian@0 89
ian@0 90 PCI Express endpoints uses INTx emulation (in-band messages) instead
ian@0 91 of IRQ pin assertion. Using INTx emulation requires interrupt
ian@0 92 sharing among devices connected to the same node (PCI bridge) while
ian@0 93 MSI is unique (non-shared) and does not require BIOS configuration
ian@0 94 support. As a result, the PCI Express technology requires MSI
ian@0 95 support for better interrupt performance.
ian@0 96
ian@0 97 Using MSI enables the device functions to support two or more
ian@0 98 vectors, which can be configured to target different CPUs to
ian@0 99 increase scalability.
ian@0 100
ian@0 101 5. Configuring a driver to use MSI/MSI-X
ian@0 102
ian@0 103 By default, the kernel will not enable MSI/MSI-X on all devices that
ian@0 104 support this capability. The CONFIG_PCI_MSI kernel option
ian@0 105 must be selected to enable MSI/MSI-X support.
ian@0 106
ian@0 107 5.1 Including MSI/MSI-X support into the kernel
ian@0 108
ian@0 109 To allow MSI/MSI-X capable device drivers to selectively enable
ian@0 110 MSI/MSI-X (using pci_enable_msi()/pci_enable_msix() as described
ian@0 111 below), the VECTOR based scheme needs to be enabled by setting
ian@0 112 CONFIG_PCI_MSI during kernel config.
ian@0 113
ian@0 114 Since the target of the inbound message is the local APIC, providing
ian@0 115 CONFIG_X86_LOCAL_APIC must be enabled as well as CONFIG_PCI_MSI.
ian@0 116
ian@0 117 5.2 Configuring for MSI support
ian@0 118
ian@0 119 Due to the non-contiguous fashion in vector assignment of the
ian@0 120 existing Linux kernel, this version does not support multiple
ian@0 121 messages regardless of a device function is capable of supporting
ian@0 122 more than one vector. To enable MSI on a device function's MSI
ian@0 123 capability structure requires a device driver to call the function
ian@0 124 pci_enable_msi() explicitly.
ian@0 125
ian@0 126 5.2.1 API pci_enable_msi
ian@0 127
ian@0 128 int pci_enable_msi(struct pci_dev *dev)
ian@0 129
ian@0 130 With this new API, a device driver that wants to have MSI
ian@0 131 enabled on its device function must call this API to enable MSI.
ian@0 132 A successful call will initialize the MSI capability structure
ian@0 133 with ONE vector, regardless of whether a device function is
ian@0 134 capable of supporting multiple messages. This vector replaces the
ian@0 135 pre-assigned dev->irq with a new MSI vector. To avoid a conflict
ian@0 136 of the new assigned vector with existing pre-assigned vector requires
ian@0 137 a device driver to call this API before calling request_irq().
ian@0 138
ian@0 139 5.2.2 API pci_disable_msi
ian@0 140
ian@0 141 void pci_disable_msi(struct pci_dev *dev)
ian@0 142
ian@0 143 This API should always be used to undo the effect of pci_enable_msi()
ian@0 144 when a device driver is unloading. This API restores dev->irq with
ian@0 145 the pre-assigned IOAPIC vector and switches a device's interrupt
ian@0 146 mode to PCI pin-irq assertion/INTx emulation mode.
ian@0 147
ian@0 148 Note that a device driver should always call free_irq() on the MSI vector
ian@0 149 that it has done request_irq() on before calling this API. Failure to do
ian@0 150 so results in a BUG_ON() and a device will be left with MSI enabled and
ian@0 151 leaks its vector.
ian@0 152
ian@0 153 5.2.3 MSI mode vs. legacy mode diagram
ian@0 154
ian@0 155 The below diagram shows the events which switch the interrupt
ian@0 156 mode on the MSI-capable device function between MSI mode and
ian@0 157 PIN-IRQ assertion mode.
ian@0 158
ian@0 159 ------------ pci_enable_msi ------------------------
ian@0 160 | | <=============== | |
ian@0 161 | MSI MODE | | PIN-IRQ ASSERTION MODE |
ian@0 162 | | ===============> | |
ian@0 163 ------------ pci_disable_msi ------------------------
ian@0 164
ian@0 165
ian@0 166 Figure 1. MSI Mode vs. Legacy Mode
ian@0 167
ian@0 168 In Figure 1, a device operates by default in legacy mode. Legacy
ian@0 169 in this context means PCI pin-irq assertion or PCI-Express INTx
ian@0 170 emulation. A successful MSI request (using pci_enable_msi()) switches
ian@0 171 a device's interrupt mode to MSI mode. A pre-assigned IOAPIC vector
ian@0 172 stored in dev->irq will be saved by the PCI subsystem and a new
ian@0 173 assigned MSI vector will replace dev->irq.
ian@0 174
ian@0 175 To return back to its default mode, a device driver should always call
ian@0 176 pci_disable_msi() to undo the effect of pci_enable_msi(). Note that a
ian@0 177 device driver should always call free_irq() on the MSI vector it has
ian@0 178 done request_irq() on before calling pci_disable_msi(). Failure to do
ian@0 179 so results in a BUG_ON() and a device will be left with MSI enabled and
ian@0 180 leaks its vector. Otherwise, the PCI subsystem restores a device's
ian@0 181 dev->irq with a pre-assigned IOAPIC vector and marks the released
ian@0 182 MSI vector as unused.
ian@0 183
ian@0 184 Once being marked as unused, there is no guarantee that the PCI
ian@0 185 subsystem will reserve this MSI vector for a device. Depending on
ian@0 186 the availability of current PCI vector resources and the number of
ian@0 187 MSI/MSI-X requests from other drivers, this MSI may be re-assigned.
ian@0 188
ian@0 189 For the case where the PCI subsystem re-assigns this MSI vector to
ian@0 190 another driver, a request to switch back to MSI mode may result
ian@0 191 in being assigned a different MSI vector or a failure if no more
ian@0 192 vectors are available.
ian@0 193
ian@0 194 5.3 Configuring for MSI-X support
ian@0 195
ian@0 196 Due to the ability of the system software to configure each vector of
ian@0 197 the MSI-X capability structure with an independent message address
ian@0 198 and message data, the non-contiguous fashion in vector assignment of
ian@0 199 the existing Linux kernel has no impact on supporting multiple
ian@0 200 messages on an MSI-X capable device functions. To enable MSI-X on
ian@0 201 a device function's MSI-X capability structure requires its device
ian@0 202 driver to call the function pci_enable_msix() explicitly.
ian@0 203
ian@0 204 The function pci_enable_msix(), once invoked, enables either
ian@0 205 all or nothing, depending on the current availability of PCI vector
ian@0 206 resources. If the PCI vector resources are available for the number
ian@0 207 of vectors requested by a device driver, this function will configure
ian@0 208 the MSI-X table of the MSI-X capability structure of a device with
ian@0 209 requested messages. To emphasize this reason, for example, a device
ian@0 210 may be capable for supporting the maximum of 32 vectors while its
ian@0 211 software driver usually may request 4 vectors. It is recommended
ian@0 212 that the device driver should call this function once during the
ian@0 213 initialization phase of the device driver.
ian@0 214
ian@0 215 Unlike the function pci_enable_msi(), the function pci_enable_msix()
ian@0 216 does not replace the pre-assigned IOAPIC dev->irq with a new MSI
ian@0 217 vector because the PCI subsystem writes the 1:1 vector-to-entry mapping
ian@0 218 into the field vector of each element contained in a second argument.
ian@0 219 Note that the pre-assigned IOAPIC dev->irq is valid only if the device
ian@0 220 operates in PIN-IRQ assertion mode. In MSI-X mode, any attempt at
ian@0 221 using dev->irq by the device driver to request for interrupt service
ian@0 222 may result unpredictabe behavior.
ian@0 223
ian@0 224 For each MSI-X vector granted, a device driver is responsible for calling
ian@0 225 other functions like request_irq(), enable_irq(), etc. to enable
ian@0 226 this vector with its corresponding interrupt service handler. It is
ian@0 227 a device driver's choice to assign all vectors with the same
ian@0 228 interrupt service handler or each vector with a unique interrupt
ian@0 229 service handler.
ian@0 230
ian@0 231 5.3.1 Handling MMIO address space of MSI-X Table
ian@0 232
ian@0 233 The PCI 3.0 specification has implementation notes that MMIO address
ian@0 234 space for a device's MSI-X structure should be isolated so that the
ian@0 235 software system can set different pages for controlling accesses to the
ian@0 236 MSI-X structure. The implementation of MSI support requires the PCI
ian@0 237 subsystem, not a device driver, to maintain full control of the MSI-X
ian@0 238 table/MSI-X PBA (Pending Bit Array) and MMIO address space of the MSI-X
ian@0 239 table/MSI-X PBA. A device driver is prohibited from requesting the MMIO
ian@0 240 address space of the MSI-X table/MSI-X PBA. Otherwise, the PCI subsystem
ian@0 241 will fail enabling MSI-X on its hardware device when it calls the function
ian@0 242 pci_enable_msix().
ian@0 243
ian@0 244 5.3.2 Handling MSI-X allocation
ian@0 245
ian@0 246 Determining the number of MSI-X vectors allocated to a function is
ian@0 247 dependent on the number of MSI capable devices and MSI-X capable
ian@0 248 devices populated in the system. The policy of allocating MSI-X
ian@0 249 vectors to a function is defined as the following:
ian@0 250
ian@0 251 #of MSI-X vectors allocated to a function = (x - y)/z where
ian@0 252
ian@0 253 x = The number of available PCI vector resources by the time
ian@0 254 the device driver calls pci_enable_msix(). The PCI vector
ian@0 255 resources is the sum of the number of unassigned vectors
ian@0 256 (new) and the number of released vectors when any MSI/MSI-X
ian@0 257 device driver switches its hardware device back to a legacy
ian@0 258 mode or is hot-removed. The number of unassigned vectors
ian@0 259 may exclude some vectors reserved, as defined in parameter
ian@0 260 NR_HP_RESERVED_VECTORS, for the case where the system is
ian@0 261 capable of supporting hot-add/hot-remove operations. Users
ian@0 262 may change the value defined in NR_HR_RESERVED_VECTORS to
ian@0 263 meet their specific needs.
ian@0 264
ian@0 265 y = The number of MSI capable devices populated in the system.
ian@0 266 This policy ensures that each MSI capable device has its
ian@0 267 vector reserved to avoid the case where some MSI-X capable
ian@0 268 drivers may attempt to claim all available vector resources.
ian@0 269
ian@0 270 z = The number of MSI-X capable devices pupulated in the system.
ian@0 271 This policy ensures that maximum (x - y) is distributed
ian@0 272 evenly among MSI-X capable devices.
ian@0 273
ian@0 274 Note that the PCI subsystem scans y and z during a bus enumeration.
ian@0 275 When the PCI subsystem completes configuring MSI/MSI-X capability
ian@0 276 structure of a device as requested by its device driver, y/z is
ian@0 277 decremented accordingly.
ian@0 278
ian@0 279 5.3.3 Handling MSI-X shortages
ian@0 280
ian@0 281 For the case where fewer MSI-X vectors are allocated to a function
ian@0 282 than requested, the function pci_enable_msix() will return the
ian@0 283 maximum number of MSI-X vectors available to the caller. A device
ian@0 284 driver may re-send its request with fewer or equal vectors indicated
ian@0 285 in the return. For example, if a device driver requests 5 vectors, but
ian@0 286 the number of available vectors is 3 vectors, a value of 3 will be
ian@0 287 returned as a result of pci_enable_msix() call. A function could be
ian@0 288 designed for its driver to use only 3 MSI-X table entries as
ian@0 289 different combinations as ABC--, A-B-C, A--CB, etc. Note that this
ian@0 290 patch does not support multiple entries with the same vector. Such
ian@0 291 attempt by a device driver to use 5 MSI-X table entries with 3 vectors
ian@0 292 as ABBCC, AABCC, BCCBA, etc will result as a failure by the function
ian@0 293 pci_enable_msix(). Below are the reasons why supporting multiple
ian@0 294 entries with the same vector is an undesirable solution.
ian@0 295
ian@0 296 - The PCI subsystem cannot determine the entry that
ian@0 297 generated the message to mask/unmask MSI while handling
ian@0 298 software driver ISR. Attempting to walk through all MSI-X
ian@0 299 table entries (2048 max) to mask/unmask any match vector
ian@0 300 is an undesirable solution.
ian@0 301
ian@0 302 - Walking through all MSI-X table entries (2048 max) to handle
ian@0 303 SMP affinity of any match vector is an undesirable solution.
ian@0 304
ian@0 305 5.3.4 API pci_enable_msix
ian@0 306
ian@0 307 int pci_enable_msix(struct pci_dev *dev, struct msix_entry *entries, int nvec)
ian@0 308
ian@0 309 This API enables a device driver to request the PCI subsystem
ian@0 310 to enable MSI-X messages on its hardware device. Depending on
ian@0 311 the availability of PCI vectors resources, the PCI subsystem enables
ian@0 312 either all or none of the requested vectors.
ian@0 313
ian@0 314 Argument 'dev' points to the device (pci_dev) structure.
ian@0 315
ian@0 316 Argument 'entries' is a pointer to an array of msix_entry structs.
ian@0 317 The number of entries is indicated in argument 'nvec'.
ian@0 318 struct msix_entry is defined in /driver/pci/msi.h:
ian@0 319
ian@0 320 struct msix_entry {
ian@0 321 u16 vector; /* kernel uses to write alloc vector */
ian@0 322 u16 entry; /* driver uses to specify entry */
ian@0 323 };
ian@0 324
ian@0 325 A device driver is responsible for initializing the field 'entry' of
ian@0 326 each element with a unique entry supported by MSI-X table. Otherwise,
ian@0 327 -EINVAL will be returned as a result. A successful return of zero
ian@0 328 indicates the PCI subsystem completed initializing each of the requested
ian@0 329 entries of the MSI-X table with message address and message data.
ian@0 330 Last but not least, the PCI subsystem will write the 1:1
ian@0 331 vector-to-entry mapping into the field 'vector' of each element. A
ian@0 332 device driver is responsible for keeping track of allocated MSI-X
ian@0 333 vectors in its internal data structure.
ian@0 334
ian@0 335 A return of zero indicates that the number of MSI-X vectors was
ian@0 336 successfully allocated. A return of greater than zero indicates
ian@0 337 MSI-X vector shortage. Or a return of less than zero indicates
ian@0 338 a failure. This failure may be a result of duplicate entries
ian@0 339 specified in second argument, or a result of no available vector,
ian@0 340 or a result of failing to initialize MSI-X table entries.
ian@0 341
ian@0 342 5.3.5 API pci_disable_msix
ian@0 343
ian@0 344 void pci_disable_msix(struct pci_dev *dev)
ian@0 345
ian@0 346 This API should always be used to undo the effect of pci_enable_msix()
ian@0 347 when a device driver is unloading. Note that a device driver should
ian@0 348 always call free_irq() on all MSI-X vectors it has done request_irq()
ian@0 349 on before calling this API. Failure to do so results in a BUG_ON() and
ian@0 350 a device will be left with MSI-X enabled and leaks its vectors.
ian@0 351
ian@0 352 5.3.6 MSI-X mode vs. legacy mode diagram
ian@0 353
ian@0 354 The below diagram shows the events which switch the interrupt
ian@0 355 mode on the MSI-X capable device function between MSI-X mode and
ian@0 356 PIN-IRQ assertion mode (legacy).
ian@0 357
ian@0 358 ------------ pci_enable_msix(,,n) ------------------------
ian@0 359 | | <=============== | |
ian@0 360 | MSI-X MODE | | PIN-IRQ ASSERTION MODE |
ian@0 361 | | ===============> | |
ian@0 362 ------------ pci_disable_msix ------------------------
ian@0 363
ian@0 364 Figure 2. MSI-X Mode vs. Legacy Mode
ian@0 365
ian@0 366 In Figure 2, a device operates by default in legacy mode. A
ian@0 367 successful MSI-X request (using pci_enable_msix()) switches a
ian@0 368 device's interrupt mode to MSI-X mode. A pre-assigned IOAPIC vector
ian@0 369 stored in dev->irq will be saved by the PCI subsystem; however,
ian@0 370 unlike MSI mode, the PCI subsystem will not replace dev->irq with
ian@0 371 assigned MSI-X vector because the PCI subsystem already writes the 1:1
ian@0 372 vector-to-entry mapping into the field 'vector' of each element
ian@0 373 specified in second argument.
ian@0 374
ian@0 375 To return back to its default mode, a device driver should always call
ian@0 376 pci_disable_msix() to undo the effect of pci_enable_msix(). Note that
ian@0 377 a device driver should always call free_irq() on all MSI-X vectors it
ian@0 378 has done request_irq() on before calling pci_disable_msix(). Failure
ian@0 379 to do so results in a BUG_ON() and a device will be left with MSI-X
ian@0 380 enabled and leaks its vectors. Otherwise, the PCI subsystem switches a
ian@0 381 device function's interrupt mode from MSI-X mode to legacy mode and
ian@0 382 marks all allocated MSI-X vectors as unused.
ian@0 383
ian@0 384 Once being marked as unused, there is no guarantee that the PCI
ian@0 385 subsystem will reserve these MSI-X vectors for a device. Depending on
ian@0 386 the availability of current PCI vector resources and the number of
ian@0 387 MSI/MSI-X requests from other drivers, these MSI-X vectors may be
ian@0 388 re-assigned.
ian@0 389
ian@0 390 For the case where the PCI subsystem re-assigned these MSI-X vectors
ian@0 391 to other drivers, a request to switch back to MSI-X mode may result
ian@0 392 being assigned with another set of MSI-X vectors or a failure if no
ian@0 393 more vectors are available.
ian@0 394
ian@0 395 5.4 Handling function implementing both MSI and MSI-X capabilities
ian@0 396
ian@0 397 For the case where a function implements both MSI and MSI-X
ian@0 398 capabilities, the PCI subsystem enables a device to run either in MSI
ian@0 399 mode or MSI-X mode but not both. A device driver determines whether it
ian@0 400 wants MSI or MSI-X enabled on its hardware device. Once a device
ian@0 401 driver requests for MSI, for example, it is prohibited from requesting
ian@0 402 MSI-X; in other words, a device driver is not permitted to ping-pong
ian@0 403 between MSI mod MSI-X mode during a run-time.
ian@0 404
ian@0 405 5.5 Hardware requirements for MSI/MSI-X support
ian@0 406
ian@0 407 MSI/MSI-X support requires support from both system hardware and
ian@0 408 individual hardware device functions.
ian@0 409
ian@0 410 5.5.1 System hardware support
ian@0 411
ian@0 412 Since the target of MSI address is the local APIC CPU, enabling
ian@0 413 MSI/MSI-X support in the Linux kernel is dependent on whether existing
ian@0 414 system hardware supports local APIC. Users should verify that their
ian@0 415 system supports local APIC operation by testing that it runs when
ian@0 416 CONFIG_X86_LOCAL_APIC=y.
ian@0 417
ian@0 418 In SMP environment, CONFIG_X86_LOCAL_APIC is automatically set;
ian@0 419 however, in UP environment, users must manually set
ian@0 420 CONFIG_X86_LOCAL_APIC. Once CONFIG_X86_LOCAL_APIC=y, setting
ian@0 421 CONFIG_PCI_MSI enables the VECTOR based scheme and the option for
ian@0 422 MSI-capable device drivers to selectively enable MSI/MSI-X.
ian@0 423
ian@0 424 Note that CONFIG_X86_IO_APIC setting is irrelevant because MSI/MSI-X
ian@0 425 vector is allocated new during runtime and MSI/MSI-X support does not
ian@0 426 depend on BIOS support. This key independency enables MSI/MSI-X
ian@0 427 support on future IOxAPIC free platforms.
ian@0 428
ian@0 429 5.5.2 Device hardware support
ian@0 430
ian@0 431 The hardware device function supports MSI by indicating the
ian@0 432 MSI/MSI-X capability structure on its PCI capability list. By
ian@0 433 default, this capability structure will not be initialized by
ian@0 434 the kernel to enable MSI during the system boot. In other words,
ian@0 435 the device function is running on its default pin assertion mode.
ian@0 436 Note that in many cases the hardware supporting MSI have bugs,
ian@0 437 which may result in system hangs. The software driver of specific
ian@0 438 MSI-capable hardware is responsible for deciding whether to call
ian@0 439 pci_enable_msi or not. A return of zero indicates the kernel
ian@0 440 successfully initialized the MSI/MSI-X capability structure of the
ian@0 441 device function. The device function is now running on MSI/MSI-X mode.
ian@0 442
ian@0 443 5.6 How to tell whether MSI/MSI-X is enabled on device function
ian@0 444
ian@0 445 At the driver level, a return of zero from the function call of
ian@0 446 pci_enable_msi()/pci_enable_msix() indicates to a device driver that
ian@0 447 its device function is initialized successfully and ready to run in
ian@0 448 MSI/MSI-X mode.
ian@0 449
ian@0 450 At the user level, users can use the command 'cat /proc/interrupts'
ian@0 451 to display the vectors allocated for devices and their interrupt
ian@0 452 MSI/MSI-X modes ("PCI-MSI"/"PCI-MSI-X"). Below shows MSI mode is
ian@0 453 enabled on a SCSI Adaptec 39320D Ultra320 controller.
ian@0 454
ian@0 455 CPU0 CPU1
ian@0 456 0: 324639 0 IO-APIC-edge timer
ian@0 457 1: 1186 0 IO-APIC-edge i8042
ian@0 458 2: 0 0 XT-PIC cascade
ian@0 459 12: 2797 0 IO-APIC-edge i8042
ian@0 460 14: 6543 0 IO-APIC-edge ide0
ian@0 461 15: 1 0 IO-APIC-edge ide1
ian@0 462 169: 0 0 IO-APIC-level uhci-hcd
ian@0 463 185: 0 0 IO-APIC-level uhci-hcd
ian@0 464 193: 138 10 PCI-MSI aic79xx
ian@0 465 201: 30 0 PCI-MSI aic79xx
ian@0 466 225: 30 0 IO-APIC-level aic7xxx
ian@0 467 233: 30 0 IO-APIC-level aic7xxx
ian@0 468 NMI: 0 0
ian@0 469 LOC: 324553 325068
ian@0 470 ERR: 0
ian@0 471 MIS: 0
ian@0 472
ian@0 473 6. FAQ
ian@0 474
ian@0 475 Q1. Are there any limitations on using the MSI?
ian@0 476
ian@0 477 A1. If the PCI device supports MSI and conforms to the
ian@0 478 specification and the platform supports the APIC local bus,
ian@0 479 then using MSI should work.
ian@0 480
ian@0 481 Q2. Will it work on all the Pentium processors (P3, P4, Xeon,
ian@0 482 AMD processors)? In P3 IPI's are transmitted on the APIC local
ian@0 483 bus and in P4 and Xeon they are transmitted on the system
ian@0 484 bus. Are there any implications with this?
ian@0 485
ian@0 486 A2. MSI support enables a PCI device sending an inbound
ian@0 487 memory write (0xfeexxxxx as target address) on its PCI bus
ian@0 488 directly to the FSB. Since the message address has a
ian@0 489 redirection hint bit cleared, it should work.
ian@0 490
ian@0 491 Q3. The target address 0xfeexxxxx will be translated by the
ian@0 492 Host Bridge into an interrupt message. Are there any
ian@0 493 limitations on the chipsets such as Intel 8xx, Intel e7xxx,
ian@0 494 or VIA?
ian@0 495
ian@0 496 A3. If these chipsets support an inbound memory write with
ian@0 497 target address set as 0xfeexxxxx, as conformed to PCI
ian@0 498 specification 2.3 or latest, then it should work.
ian@0 499
ian@0 500 Q4. From the driver point of view, if the MSI is lost because
ian@0 501 of errors occurring during inbound memory write, then it may
ian@0 502 wait forever. Is there a mechanism for it to recover?
ian@0 503
ian@0 504 A4. Since the target of the transaction is an inbound memory
ian@0 505 write, all transaction termination conditions (Retry,
ian@0 506 Master-Abort, Target-Abort, or normal completion) are
ian@0 507 supported. A device sending an MSI must abide by all the PCI
ian@0 508 rules and conditions regarding that inbound memory write. So,
ian@0 509 if a retry is signaled it must retry, etc... We believe that
ian@0 510 the recommendation for Abort is also a retry (refer to PCI
ian@0 511 specification 2.3 or latest).