PCI/MSI: Document pci_alloc_irq_vectors(), deprecate pci_enable_msi()

"vectors" get allocated. MSI requires contiguous blocks of vectors

"vectors" get allocated. MSI requires contiguous blocks of vectors

while MSI-X can allocate several individual ones.

while MSI-X can allocate several individual ones.

MSI capability can be enabled by calling pci_enable_msi() or

MSI capability can be enabled by calling pci_alloc_irq_vectors() with the

pci_enable_msix() before calling request_irq(). This causes

PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This

the PCI support to program CPU vector data into the PCI device

causes the PCI support to program CPU vector data into the PCI device

capability registers.

capability registers. Many architectures, chip-sets, or BIOSes do NOT

support MSI or MSI-X and a call to pci_alloc_irq_vectors with just

If your PCI device supports both, try to enable MSI-X first.

the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always

Only one can be enabled at a time.  Many architectures, chip-sets,

specify PCI_IRQ_LEGACY as well.

or BIOSes do NOT support MSI or MSI-X and the call to pci_enable_msi/msix

will fail. This is important to note since many drivers have

Drivers that have different interrupt handlers for MSI/MSI-X and

two (or more) interrupt handlers: one for MSI/MSI-X and another for IRQs.

legacy INTx should chose the right one based on the msi_enabled

They choose which handler to register with request_irq() based on the

and msix_enabled flags in the pci_dev structure after calling

return value from pci_enable_msi/msix().

pci_alloc_irq_vectors.

There are (at least) two really good reasons for using MSI:

There are (at least) two really good reasons for using MSI:

1) MSI is an exclusive interrupt vector by definition.

1) MSI is an exclusive interrupt vector by definition.