aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation
diff options
context:
space:
mode:
authorMichael Ellerman <michael@ellerman.id.au>2007-09-19 22:48:23 -0400
committerGreg Kroah-Hartman <gregkh@suse.de>2007-10-12 18:03:16 -0400
commit4904e23b6b37c748a35bb2bd14ea325d0592e671 (patch)
treed2628842a08731846af6c8bd80f2b8b63626bb1f /Documentation
parent346ca04d050ac48ceb8e4a6b1c76c2d7fd5d1a6a (diff)
PCI: Remove no longer correct documentation regarding MSI vector assignment
The MSI vector reservation system described in Documentation/MSI-HOWTO.txt was removed by Eric in 92db6d10bc1bc43330a4c540fa5b64c83d9d865f. Remove the references to it in the documentation. While we're here ยง 5.5.1 refers to x86 hardware requirements, so make that clear. Signed-off-by: Michael Ellerman <michael@ellerman.id.au> Cc: Eric W. Biederman <ebiederm@xmission.com> Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/MSI-HOWTO.txt69
1 files changed, 4 insertions, 65 deletions
diff --git a/Documentation/MSI-HOWTO.txt b/Documentation/MSI-HOWTO.txt
index 0d8240774fca..a51f693c1541 100644
--- a/Documentation/MSI-HOWTO.txt
+++ b/Documentation/MSI-HOWTO.txt
@@ -241,68 +241,7 @@ address space of the MSI-X table/MSI-X PBA. Otherwise, the PCI subsystem
241will fail enabling MSI-X on its hardware device when it calls the function 241will fail enabling MSI-X on its hardware device when it calls the function
242pci_enable_msix(). 242pci_enable_msix().
243 243
2445.3.2 Handling MSI-X allocation 2445.3.2 API pci_enable_msix
245
246Determining the number of MSI-X vectors allocated to a function is
247dependent on the number of MSI capable devices and MSI-X capable
248devices populated in the system. The policy of allocating MSI-X
249vectors to a function is defined as the following:
250
251#of MSI-X vectors allocated to a function = (x - y)/z where
252
253x = The number of available PCI vector resources by the time
254 the device driver calls pci_enable_msix(). The PCI vector
255 resources is the sum of the number of unassigned vectors
256 (new) and the number of released vectors when any MSI/MSI-X
257 device driver switches its hardware device back to a legacy
258 mode or is hot-removed. The number of unassigned vectors
259 may exclude some vectors reserved, as defined in parameter
260 NR_HP_RESERVED_VECTORS, for the case where the system is
261 capable of supporting hot-add/hot-remove operations. Users
262 may change the value defined in NR_HR_RESERVED_VECTORS to
263 meet their specific needs.
264
265y = The number of MSI capable devices populated in the system.
266 This policy ensures that each MSI capable device has its
267 vector reserved to avoid the case where some MSI-X capable
268 drivers may attempt to claim all available vector resources.
269
270z = The number of MSI-X capable devices populated in the system.
271 This policy ensures that maximum (x - y) is distributed
272 evenly among MSI-X capable devices.
273
274Note that the PCI subsystem scans y and z during a bus enumeration.
275When the PCI subsystem completes configuring MSI/MSI-X capability
276structure of a device as requested by its device driver, y/z is
277decremented accordingly.
278
2795.3.3 Handling MSI-X shortages
280
281For the case where fewer MSI-X vectors are allocated to a function
282than requested, the function pci_enable_msix() will return the
283maximum number of MSI-X vectors available to the caller. A device
284driver may re-send its request with fewer or equal vectors indicated
285in the return. For example, if a device driver requests 5 vectors, but
286the number of available vectors is 3 vectors, a value of 3 will be
287returned as a result of pci_enable_msix() call. A function could be
288designed for its driver to use only 3 MSI-X table entries as
289different combinations as ABC--, A-B-C, A--CB, etc. Note that this
290patch does not support multiple entries with the same vector. Such
291attempt by a device driver to use 5 MSI-X table entries with 3 vectors
292as ABBCC, AABCC, BCCBA, etc will result as a failure by the function
293pci_enable_msix(). Below are the reasons why supporting multiple
294entries with the same vector is an undesirable solution.
295
296 - The PCI subsystem cannot determine the entry that
297 generated the message to mask/unmask MSI while handling
298 software driver ISR. Attempting to walk through all MSI-X
299 table entries (2048 max) to mask/unmask any match vector
300 is an undesirable solution.
301
302 - Walking through all MSI-X table entries (2048 max) to handle
303 SMP affinity of any match vector is an undesirable solution.
304
3055.3.4 API pci_enable_msix
306 245
307int pci_enable_msix(struct pci_dev *dev, struct msix_entry *entries, int nvec) 246int pci_enable_msix(struct pci_dev *dev, struct msix_entry *entries, int nvec)
308 247
@@ -339,7 +278,7 @@ a failure. This failure may be a result of duplicate entries
339specified in second argument, or a result of no available vector, 278specified in second argument, or a result of no available vector,
340or a result of failing to initialize MSI-X table entries. 279or a result of failing to initialize MSI-X table entries.
341 280
3425.3.5 API pci_disable_msix 2815.3.3 API pci_disable_msix
343 282
344void pci_disable_msix(struct pci_dev *dev) 283void pci_disable_msix(struct pci_dev *dev)
345 284
@@ -349,7 +288,7 @@ always call free_irq() on all MSI-X vectors it has done request_irq()
349on before calling this API. Failure to do so results in a BUG_ON() and 288on before calling this API. Failure to do so results in a BUG_ON() and
350a device will be left with MSI-X enabled and leaks its vectors. 289a device will be left with MSI-X enabled and leaks its vectors.
351 290
3525.3.6 MSI-X mode vs. legacy mode diagram 2915.3.4 MSI-X mode vs. legacy mode diagram
353 292
354The below diagram shows the events which switch the interrupt 293The below diagram shows the events which switch the interrupt
355mode on the MSI-X capable device function between MSI-X mode and 294mode on the MSI-X capable device function between MSI-X mode and
@@ -407,7 +346,7 @@ between MSI mod MSI-X mode during a run-time.
407MSI/MSI-X support requires support from both system hardware and 346MSI/MSI-X support requires support from both system hardware and
408individual hardware device functions. 347individual hardware device functions.
409 348
4105.5.1 System hardware support 3495.5.1 Required x86 hardware support
411 350
412Since the target of MSI address is the local APIC CPU, enabling 351Since the target of MSI address is the local APIC CPU, enabling
413MSI/MSI-X support in the Linux kernel is dependent on whether existing 352MSI/MSI-X support in the Linux kernel is dependent on whether existing