The MSI Driver Guide HOWTO

Http://www.mjmwired.net/kernel/Documentation/MSI-HOWTO.txt 1 The MSI Driver Guide HOWTO 2 Tom L. Nguyen Tom.l.nguyen[at 		]intel[dot]com 3 10/03/2003 4 revised FEB 5 Martine 6 Revised June, by Tom L. Nguyen 7 8 1. About this guide 9 A guide describes the basics of message signaled interrupts (MSI), the advantages of using MS I over traditional interrupt mechanisms, and you to enable your driver to the use MSI or msi-x.
Also included is the Frequently asked Questions (FAQ) section.  1.1 Terminology PCI devices can be single-function or multi-function. In either case, talks the about enabling or disabling MSI on a ' device function, ' it is referring to one Specific PCI device and function and all functions on a PCI device (unless the PCI device has only one one functi
ON). 22 23 2. Copyright 2003 Intel Corporation 24 25 3.
What is Msi/msi-x? Message SignaleD Interrupt (MSI), as described in the PCI local bus specification Revision 2.3 or later, are an optional feature, and a Required feature for PCI Express devices. MSI enables a device function from request service by sending a Inbound Memory Write on it PCI bus to the FSB as a M Essage Signal Interrupt transaction. Because MSI is-generated in the form of a Memory Write, all transaction conditions, such as a retry, Master-abort, T
Arget-abort or normal completion, are supported. A PCI device that supports MSI must also support pin IRQ assertion Notoginseng interrupt mechanism to provide backward Tibility for systems that does not support MSI. 	In systems which support MSI, the bus driver is-responsible for initializing the "message address" and message data of 40
The device function ' s MSI/MSI-X capability structure during device-initial. The MSI capable device function indicates MSI support by implementing the MSI/MSI-X capabilityE in its PCI capability list. The device function may implement both the MSI capability structure the MSI-X capability;
However, the bus driver should does not enable both. The MSI capability structure contains message control register, the "address register" and "message Data regist Er. These registers Wuyi provide bus driver control over MSI. The Message control register indicates the MSI capability supported by the device. The message, address register, specifies the target address, and the message Data register specifies the characteristic s of the message. To request service, the device function writes the content of the ' message Data ' to the target address.
The device and its software driver are prohibited from writing to these registers. The MSI-X capability structure is a optional extension to MSI. It uses an independent and separate capability structure. There are some key advantages to implementing the msi-x capAbility structure over the MSI capability structure as described below.
64-support a larger maximum number of vectors per function. 66-provide the ability for system software to configure all vectors with a independent message address and MES
Sage data, specified by a table this resides in Memory. The 70-msi and Msi-x both support per-vector masking. Per-vector Masking is a optional extension of MSI but a required to the for feature.  Per-vector masking provides the kernel ability to mask/unmask a single MSI while running its interrupt service routine. If Per-vector Masking is supported, then the device driver should provide the Hardware/software
N to ensure this device generates MSI the driver wants it to does so. 78 79 4.
Why use MSI? BA Bayi as a benefit to the simplification of board design, MSI allows board designers to remove Out-of-band interrupt R Outing. MSI is anotherWards a legacy-free environment.  Due to increasing pressure in chipset and processor packages to + reduce pin count, the need for interrupt pins Expected to the diminish over time.
Devices, due to pin constraints, could implement messages to increase performance. The PCI Express endpoints uses INTx emulation (In-band messages) instead the-a-for IRQ pin assertion. Using INTx emulation requires interrupt-sharing-among-devices-to-connected node (PCI Bridge) while the MSI is U Nique (non-shared) and does not require BIOS configuration support.
As a result, the PCI Express technology requires MSI support for better interrupt performance. The Using MSI enables the device functions to support two or more vectors, which can is configured to target Differe
NT CPUs to increase scalability. 100 101 5. Configuring a driver to use Msi/msi-x 102 with default, the kernel would not enable msi/msi-x on all devices Pport this capability. The Config_pci_msi Kernel option must is selected to enable msi/msi-x support.  The 5.1 including msi/msi-x support into the kernel 108-109 to allow-msi/msi-x capable device to drivers Enable Msi/msi-x (using Pci_enable_msi ()/pci_enable_msix () as described below), the VECTOR based scheme needs to
Be-enabled by setting 112 Config_pci_msi during kernel CONFIG.  113 114 Since The target of the inbound message being the local APIC, providing-
As Config_pci_msi. 116 117 5.2 Configuring for MSI support 118 119 Due to the non-contiguous in vector fashion of the assignment Ng Linux Kernel, this version does not support multiple 121 messages regardless of a device the function is capable of support ING 122 more than one vector. To enable MSI in a device function ' s MSI 123 capability structure requires a device driver to call the function 124
Able_msi () explicitly. 126 5.2.1 API pci_enable_msi 127 128 int Pci_enable_msi (struct Pci_dev *dev) 129 130 with the new API, a device driver that wants to have MSI 131 enabled in its device function
Must call this API to enable MSI. 132 A successful call would initialize the MSI capability structure with one vector, regardless of whether A device fun Ction is 134 capable of supporting multiple messages. This vector replaces the 135 pre-assigned DEV->IRQ with a new MSI vector. To avoid a conflict 136 of the "new assigned vector with existing pre-assigned vector requires 137 a device driver to call
This API before calling Request_irq (). 138 139 5.2.2 API Pci_disable_msi 140 (pci_disable_msi struct) Pci_dev *dev this API 143 is U Sed to undo the effect of Pci_enable_msi () 144 When a device driver is unloading. This API restores DEV->IRQ with 145 the pre-assigned ioapic vector and switches a device ' s interrupt 146 mode to PCI Pi
N-IRQ assertion/intx emulation mode. 147 148 Note This a device driver should always call FREE_IRQ () on the MSI vector 149 that it has done REQUEST_IRQ () on before calling this API.
Failure to did results in a bug_on () and a device'll is left with MSI-enabled and 151 its vector. 	152 153 5.2.3 MSI mode vs. Legacy mode diagram 154 the the below diagram shows the events which switch the interrupt 156
Mode on the msi-capable device function between MSI mode and 157 PIN-IRQ assertion mode.	     158 159------------Pci_enable_msi------------------------160 | | 			 <=============== |
| 161 |	  	     	MSI MODE | |
PIN-IRQ Assertion MODE | 	     162 | |			 ===============> |
| 163------------Pci_disable_msi------------------------164 165 166 1. MSI mode vs. Legacy mode 167 Figure 1, a device operates by default in Legacy mode. Legacy 169 in the context means PCI Pin-irq assertion or pci-express INTx 170. A successful MSI request (using Pci_enable_msi ()) Switches 171 A device ' s interrupt mode to MSI mode. A pre-assigned IOAPIC vector 172 stored in DEV-&GT;IRQ is saved by the PCI subsystem and a new 173 assigned MSI vector would replace Dev
->irq. 174 175 to-return-to-it default mode, a device driver should always call 176 Pci_disable_msi () to undo the effect O F Pci_enable_msi (). Note This a 177 device driver should always call FREE_IRQ () on the MSI vector it has 178 do REQUEST_IRQ () on before call ing Pci_disable_msi (). Failure to did 179 so results in a bug_on () and a device would be left with MSI enabled and 180 the its vector.
Otherwise, the PCI subsystem restores a device ' s 181 dev->irq with a pre-assigned vector and ioapic the marks
The unused MSI vector as. 183 184 Once being marked as unused, there is no guarantee that the PCI 185 subsystem'll reserve this MSI vector for a Device. Depending on 186 the availability's PCI vector and the number of 187 Msi/msi-x requests from other DRIV
ERs, this MSI is re-assigned. 188 189 for the case where the PCI subsystem re-assigns this MSI vector to 190 another driver, a request to switch back to MSI mode could 191 in being
Assigned a different MSI vector or a failure if no more vectors are available.
193 194 5.3 Configuring for Msi-x support 195 196 Due to the ability of the "system software to configure" each vector of  197 The MSI-X capability structure with a independent message address 198 and message data, the non-contiguous fashion in Vector Assignment of 199 the existing Linux kernel has no impact on supporting multiple/messages on a msi-x capable Device functions. To enable MSI-X on 201 A device function ' s MSI-X capability structure requires its device
Pci_enable_msix () explicitly. 203 204 the function pci_enable_msix (), once invoked, enables either all or nothing, and 205 on the current depending Ility of PCI Vector 206 resources. If the PCI vector are available for the number 207 of vectors requested by a device driver,This function would configure the Msi-x table of the MSI-X capability structure of a device with 209 requested .	To emphasize this reason, for example, a device 210 may is capable for supporting the maximum of-vectors while its 211 Software driver usually may request 4 vectors. It is recommended 212 that device driver should call this function once during the 213 initialization phase of the Dev
Ice driver.  214 215 Unlike the function Pci_enable_msi (), the function pci_enable_msix () 216 does not replace the pre-assigned ioapic  Dev->irq with a new MSI 217 vector because the PCI subsystem writes the 1:1 vector-to-entry mapping to the field
 Vector of each element contained in a second argument.