Commit 870d3be1249b1397395ed3164987397993a16d91
Exists in
master
and in
4 other branches
Merge branch 'docs-move' of git://git.kernel.org/pub/scm/linux/kernel/git/rdunlap/linux-docs
* 'docs-move' of git://git.kernel.org/pub/scm/linux/kernel/git/rdunlap/linux-docs: Docs: MSI-HOWTO: MSI -> MSIs Docs: MSI-HOWTO: Insert a comma Docs: MSI-HOWTO: can -> could Docs: MSI-HOWTO: Use `unknown ...' rather than `... know about.' Docs: MSI-HOWTO: may -> might Docs: MSI-HOWTO: Insert a comma Docs: MSI-HOWTO: API -> function Docs: MSI-HOWTO: , -> ; Docs: MSI-HOWTO: Move a sentence to another paragraph Docs: MSI-HOWTO: Insert `that' Docs: MSI-HOWTO: Offset modifier with a comma, and insert `yet' for emphasis Docs: MSI-HOWTO: Put the `because' subordinate clause first Docs: MSI-HOWTO: Streamline some wording Docs: MSI-HOWTO: `asked for' -> `requested' Docs: MSI-HOWTO: Use present tense and streamline some wording Docs: MSI-HOWTO: Use the subjunctive, and change `can' to `may'
Showing 1 changed file Side-by-side Diff
Documentation/PCI/MSI-HOWTO.txt
... | ... | @@ -45,7 +45,7 @@ |
45 | 45 | bridges). In order to ensure that all the data has arrived in memory, |
46 | 46 | the interrupt handler must read a register on the device which raised |
47 | 47 | the interrupt. PCI transaction ordering rules require that all the data |
48 | -arrives in memory before the value can be returned from the register. | |
48 | +arrive in memory before the value may be returned from the register. | |
49 | 49 | Using MSIs avoids this problem as the interrupt-generating write cannot |
50 | 50 | pass the data writes, so by the time the interrupt is raised, the driver |
51 | 51 | knows that all the data has arrived in memory. |
52 | 52 | |
... | ... | @@ -86,13 +86,13 @@ |
86 | 86 | |
87 | 87 | int pci_enable_msi(struct pci_dev *dev) |
88 | 88 | |
89 | -A successful call will allocate ONE interrupt to the device, regardless | |
90 | -of how many MSIs the device supports. The device will be switched from | |
89 | +A successful call allocates ONE interrupt to the device, regardless | |
90 | +of how many MSIs the device supports. The device is switched from | |
91 | 91 | pin-based interrupt mode to MSI mode. The dev->irq number is changed |
92 | -to a new number which represents the message signaled interrupt. | |
93 | -This function should be called before the driver calls request_irq() | |
94 | -since enabling MSIs disables the pin-based IRQ and the driver will not | |
95 | -receive interrupts on the old interrupt. | |
92 | +to a new number which represents the message signaled interrupt; | |
93 | +consequently, this function should be called before the driver calls | |
94 | +request_irq(), because an MSI is delivered via a vector that is | |
95 | +different from the vector of a pin-based interrupt. | |
96 | 96 | |
97 | 97 | 4.2.2 pci_enable_msi_block |
98 | 98 | |
99 | 99 | |
100 | 100 | |
... | ... | @@ -111,20 +111,20 @@ |
111 | 111 | |
112 | 112 | If this function returns a negative number, it indicates an error and |
113 | 113 | the driver should not attempt to request any more MSI interrupts for |
114 | -this device. If this function returns a positive number, it will be | |
115 | -less than 'count' and indicate the number of interrupts that could have | |
116 | -been allocated. In neither case will the irq value have been | |
117 | -updated, nor will the device have been switched into MSI mode. | |
114 | +this device. If this function returns a positive number, it is | |
115 | +less than 'count' and indicates the number of interrupts that could have | |
116 | +been allocated. In neither case is the irq value updated or the device | |
117 | +switched into MSI mode. | |
118 | 118 | |
119 | 119 | The device driver must decide what action to take if |
120 | -pci_enable_msi_block() returns a value less than the number asked for. | |
121 | -Some devices can make use of fewer interrupts than the maximum they | |
122 | -request; in this case the driver should call pci_enable_msi_block() | |
120 | +pci_enable_msi_block() returns a value less than the number requested. | |
121 | +For instance, the driver could still make use of fewer interrupts; | |
122 | +in this case the driver should call pci_enable_msi_block() | |
123 | 123 | again. Note that it is not guaranteed to succeed, even when the |
124 | 124 | 'count' has been reduced to the value returned from a previous call to |
125 | 125 | pci_enable_msi_block(). This is because there are multiple constraints |
126 | 126 | on the number of vectors that can be allocated; pci_enable_msi_block() |
127 | -will return as soon as it finds any constraint that doesn't allow the | |
127 | +returns as soon as it finds any constraint that doesn't allow the | |
128 | 128 | call to succeed. |
129 | 129 | |
130 | 130 | 4.2.3 pci_disable_msi |
... | ... | @@ -137,10 +137,10 @@ |
137 | 137 | interrupt(s). The interrupt may subsequently be assigned to another |
138 | 138 | device, so drivers should not cache the value of dev->irq. |
139 | 139 | |
140 | -A device driver must always call free_irq() on the interrupt(s) | |
141 | -for which it has called request_irq() before calling this function. | |
142 | -Failure to do so will result in a BUG_ON(), the device will be left with | |
143 | -MSI enabled and will leak its vector. | |
140 | +Before calling this function, a device driver must always call free_irq() | |
141 | +on any interrupt for which it previously called request_irq(). | |
142 | +Failure to do so results in a BUG_ON(), leaving the device with | |
143 | +MSI enabled and thus leaking its vector. | |
144 | 144 | |
145 | 145 | 4.3 Using MSI-X |
146 | 146 | |
147 | 147 | |
... | ... | @@ -155,10 +155,10 @@ |
155 | 155 | }; |
156 | 156 | |
157 | 157 | This allows for the device to use these interrupts in a sparse fashion; |
158 | -for example it could use interrupts 3 and 1027 and allocate only a | |
158 | +for example, it could use interrupts 3 and 1027 and yet allocate only a | |
159 | 159 | two-element array. The driver is expected to fill in the 'entry' value |
160 | -in each element of the array to indicate which entries it wants the kernel | |
161 | -to assign interrupts for. It is invalid to fill in two entries with the | |
160 | +in each element of the array to indicate for which entries the kernel | |
161 | +should assign interrupts; it is invalid to fill in two entries with the | |
162 | 162 | same number. |
163 | 163 | |
164 | 164 | 4.3.1 pci_enable_msix |
... | ... | @@ -168,10 +168,11 @@ |
168 | 168 | Calling this function asks the PCI subsystem to allocate 'nvec' MSIs. |
169 | 169 | The 'entries' argument is a pointer to an array of msix_entry structs |
170 | 170 | which should be at least 'nvec' entries in size. On success, the |
171 | -function will return 0 and the device will have been switched into | |
172 | -MSI-X interrupt mode. The 'vector' elements in each entry will have | |
173 | -been filled in with the interrupt number. The driver should then call | |
174 | -request_irq() for each 'vector' that it decides to use. | |
171 | +device is switched into MSI-X mode and the function returns 0. | |
172 | +The 'vector' member in each entry is populated with the interrupt number; | |
173 | +the driver should then call request_irq() for each 'vector' that it | |
174 | +decides to use. The device driver is responsible for keeping track of the | |
175 | +interrupts assigned to the MSI-X vectors so it can free them again later. | |
175 | 176 | |
176 | 177 | If this function returns a negative number, it indicates an error and |
177 | 178 | the driver should not attempt to allocate any more MSI-X interrupts for |
178 | 179 | |
179 | 180 | |
... | ... | @@ -181,16 +182,14 @@ |
181 | 182 | |
182 | 183 | This function, in contrast with pci_enable_msi(), does not adjust |
183 | 184 | dev->irq. The device will not generate interrupts for this interrupt |
184 | -number once MSI-X is enabled. The device driver is responsible for | |
185 | -keeping track of the interrupts assigned to the MSI-X vectors so it can | |
186 | -free them again later. | |
185 | +number once MSI-X is enabled. | |
187 | 186 | |
188 | 187 | Device drivers should normally call this function once per device |
189 | 188 | during the initialization phase. |
190 | 189 | |
191 | -It is ideal if drivers can cope with a variable number of MSI-X interrupts, | |
190 | +It is ideal if drivers can cope with a variable number of MSI-X interrupts; | |
192 | 191 | there are many reasons why the platform may not be able to provide the |
193 | -exact number a driver asks for. | |
192 | +exact number that a driver asks for. | |
194 | 193 | |
195 | 194 | A request loop to achieve that might look like: |
196 | 195 | |
197 | 196 | |
... | ... | @@ -212,15 +211,15 @@ |
212 | 211 | |
213 | 212 | void pci_disable_msix(struct pci_dev *dev) |
214 | 213 | |
215 | -This API should be used to undo the effect of pci_enable_msix(). It frees | |
214 | +This function should be used to undo the effect of pci_enable_msix(). It frees | |
216 | 215 | the previously allocated message signaled interrupts. The interrupts may |
217 | 216 | subsequently be assigned to another device, so drivers should not cache |
218 | 217 | the value of the 'vector' elements over a call to pci_disable_msix(). |
219 | 218 | |
220 | -A device driver must always call free_irq() on the interrupt(s) | |
221 | -for which it has called request_irq() before calling this function. | |
222 | -Failure to do so will result in a BUG_ON(), the device will be left with | |
223 | -MSI enabled and will leak its vector. | |
219 | +Before calling this function, a device driver must always call free_irq() | |
220 | +on any interrupt for which it previously called request_irq(). | |
221 | +Failure to do so results in a BUG_ON(), leaving the device with | |
222 | +MSI-X enabled and thus leaking its vector. | |
224 | 223 | |
225 | 224 | 4.3.3 The MSI-X Table |
226 | 225 | |
227 | 226 | |
... | ... | @@ -232,10 +231,10 @@ |
232 | 231 | 4.4 Handling devices implementing both MSI and MSI-X capabilities |
233 | 232 | |
234 | 233 | If a device implements both MSI and MSI-X capabilities, it can |
235 | -run in either MSI mode or MSI-X mode but not both simultaneously. | |
234 | +run in either MSI mode or MSI-X mode, but not both simultaneously. | |
236 | 235 | This is a requirement of the PCI spec, and it is enforced by the |
237 | 236 | PCI layer. Calling pci_enable_msi() when MSI-X is already enabled or |
238 | -pci_enable_msix() when MSI is already enabled will result in an error. | |
237 | +pci_enable_msix() when MSI is already enabled results in an error. | |
239 | 238 | If a device driver wishes to switch between MSI and MSI-X at runtime, |
240 | 239 | it must first quiesce the device, then switch it back to pin-interrupt |
241 | 240 | mode, before calling pci_enable_msi() or pci_enable_msix() and resuming |
... | ... | @@ -251,7 +250,7 @@ |
251 | 250 | above, MSI-X supports any number of interrupts between 1 and 2048. |
252 | 251 | In constrast, MSI is restricted to a maximum of 32 interrupts (and |
253 | 252 | must be a power of two). In addition, the MSI interrupt vectors must |
254 | -be allocated consecutively, so the system may not be able to allocate | |
253 | +be allocated consecutively, so the system might not be able to allocate | |
255 | 254 | as many vectors for MSI as it could for MSI-X. On some platforms, MSI |
256 | 255 | interrupts must all be targeted at the same set of CPUs whereas MSI-X |
257 | 256 | interrupts can all be targeted at different CPUs. |
... | ... | @@ -281,7 +280,7 @@ |
281 | 280 | |
282 | 281 | Using 'lspci -v' (as root) may show some devices with "MSI", "Message |
283 | 282 | Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities |
284 | -has an 'Enable' flag which will be followed with either "+" (enabled) | |
283 | +has an 'Enable' flag which is followed with either "+" (enabled) | |
285 | 284 | or "-" (disabled). |
286 | 285 | |
287 | 286 | |
... | ... | @@ -298,7 +297,7 @@ |
298 | 297 | |
299 | 298 | Some host chipsets simply don't support MSIs properly. If we're |
300 | 299 | lucky, the manufacturer knows this and has indicated it in the ACPI |
301 | -FADT table. In this case, Linux will automatically disable MSIs. | |
300 | +FADT table. In this case, Linux automatically disables MSIs. | |
302 | 301 | Some boards don't include this information in the table and so we have |
303 | 302 | to detect them ourselves. The complete list of these is found near the |
304 | 303 | quirk_disable_all_msi() function in drivers/pci/quirks.c. |
... | ... | @@ -317,7 +316,7 @@ |
317 | 316 | PCI configuration space (especially the Hypertransport chipsets such |
318 | 317 | as the nVidia nForce and Serverworks HT2000). As with host chipsets, |
319 | 318 | Linux mostly knows about them and automatically enables MSIs if it can. |
320 | -If you have a bridge which Linux doesn't yet know about, you can enable | |
319 | +If you have a bridge unknown to Linux, you can enable | |
321 | 320 | MSIs in configuration space using whatever method you know works, then |
322 | 321 | enable MSIs on that bridge by doing: |
323 | 322 | |
... | ... | @@ -327,7 +326,7 @@ |
327 | 326 | 0000:00:0e.0). |
328 | 327 | |
329 | 328 | To disable MSIs, echo 0 instead of 1. Changing this value should be |
330 | -done with caution as it can break interrupt handling for all devices | |
329 | +done with caution as it could break interrupt handling for all devices | |
331 | 330 | below this bridge. |
332 | 331 | |
333 | 332 | Again, please notify linux-pci@vger.kernel.org of any bridges that need |
... | ... | @@ -336,7 +335,7 @@ |
336 | 335 | 5.3. Disabling MSIs on a single device |
337 | 336 | |
338 | 337 | Some devices are known to have faulty MSI implementations. Usually this |
339 | -is handled in the individual device driver but occasionally it's necessary | |
338 | +is handled in the individual device driver, but occasionally it's necessary | |
340 | 339 | to handle this with a quirk. Some drivers have an option to disable use |
341 | 340 | of MSI. While this is a convenient workaround for the driver author, |
342 | 341 | it is not good practise, and should not be emulated. |
... | ... | @@ -350,7 +349,7 @@ |
350 | 349 | have enabled CONFIG_PCI_MSI. |
351 | 350 | |
352 | 351 | Then, 'lspci -t' gives the list of bridges above a device. Reading |
353 | -/sys/bus/pci/devices/*/msi_bus will tell you whether MSI are enabled (1) | |
352 | +/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) | |
354 | 353 | or disabled (0). If 0 is found in any of the msi_bus files belonging |
355 | 354 | to bridges between the PCI root and the device, MSIs are disabled. |
356 | 355 |