kpriv/linux-hardened
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Documentation: PCI: convert MSI-HOWTO.txt to reST

Browse source 
Convert plain text documentation to reStructuredText format and add it to
Sphinx TOC tree.  No essential content change.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
Changbin Du 2019-05-14 22:47:27 +08:00 committed by Bjorn Helgaas
parent 4d2c729c62
commit 3b9bae029b
2 changed files with 52 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
Documentation/PCI/index.rst
View file

@ -11,3 +11,4 @@ Linux PCI Bus Subsystem
pci pci
picebus-howto picebus-howto
pci-iov-howto pci-iov-howto
msi-howto

83
Documentation/PCI/MSI-HOWTO.txt → Documentation/PCI/msi-howto.rst
View file

@ -1,13 +1,16 @@
The MSI Driver Guide HOWTO .. SPDX-License-Identifier: GPL-2.0
Tom L Nguyen tom.l.nguyen@intel.com .. include:: <isonum.txt>
10/03/2003
Revised Feb 12, 2004 by Martine Silbermann
email: Martine.Silbermann@hp.com
Revised Jun 25, 2004 by Tom L Nguyen
Revised Jul 9, 2008 by Matthew Wilcox <willy@linux.intel.com>
Copyright 2003, 2008 Intel Corporation
1. About this guide ==========================
The MSI Driver Guide HOWTO
==========================
:Authors: Tom L Nguyen; Martine Silbermann; Matthew Wilcox
:Copyright: 2003, 2008 Intel Corporation
About this guide
================
This guide describes the basics of Message Signaled Interrupts (MSIs), This guide describes the basics of Message Signaled Interrupts (MSIs),
the advantages of using MSI over traditional interrupt mechanisms, how the advantages of using MSI over traditional interrupt mechanisms, how
@ -15,7 +18,8 @@ to change your driver to use MSI or MSI-X and some basic diagnostics to
try if a device doesn't support MSIs. try if a device doesn't support MSIs.
2. What are MSIs? What are MSIs?
==============
A Message Signaled Interrupt is a write from the device to a special A Message Signaled Interrupt is a write from the device to a special
address which causes an interrupt to be received by the CPU. address which causes an interrupt to be received by the CPU.
@ -29,7 +33,8 @@ Devices may support both MSI and MSI-X, but only one can be enabled at
a time. a time.
3. Why use MSIs? Why use MSIs?
=============
There are three reasons why using MSIs can give an advantage over There are three reasons why using MSIs can give an advantage over
traditional pin-based interrupts. traditional pin-based interrupts.
@ -61,14 +66,16 @@ Other possible designs include giving one interrupt to each packet queue
in a network card or each port in a storage controller. in a network card or each port in a storage controller.
4. How to use MSIs How to use MSIs
===============
PCI devices are initialised to use pin-based interrupts. The device PCI devices are initialised to use pin-based interrupts. The device
driver has to set up the device to use MSI or MSI-X. Not all machines driver has to set up the device to use MSI or MSI-X. Not all machines
support MSIs correctly, and for those machines, the APIs described below support MSIs correctly, and for those machines, the APIs described below
will simply fail and the device will continue to use pin-based interrupts. will simply fail and the device will continue to use pin-based interrupts.
4.1 Include kernel support for MSIs Include kernel support for MSIs
-------------------------------
To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI To support MSI or MSI-X, the kernel must be built with the CONFIG_PCI_MSI
option enabled. This option is only available on some architectures, option enabled. This option is only available on some architectures,
@ -76,14 +83,15 @@ and it may depend on some other options also being set. For example,
on x86, you must also enable X86_UP_APIC or SMP in order to see the on x86, you must also enable X86_UP_APIC or SMP in order to see the
CONFIG_PCI_MSI option. CONFIG_PCI_MSI option.
4.2 Using MSI Using MSI
---------
Most of the hard work is done for the driver in the PCI layer. The driver Most of the hard work is done for the driver in the PCI layer. The driver
simply has to request that the PCI layer set up the MSI capability for this simply has to request that the PCI layer set up the MSI capability for this
device. device.
To automatically use MSI or MSI-X interrupt vectors, use the following To automatically use MSI or MSI-X interrupt vectors, use the following
function: function::
int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs, int pci_alloc_irq_vectors(struct pci_dev *dev, unsigned int min_vecs,
unsigned int max_vecs, unsigned int flags); unsigned int max_vecs, unsigned int flags);
@ -101,12 +109,12 @@ any possible kind of interrupt. If the PCI_IRQ_AFFINITY flag is set,
pci_alloc_irq_vectors() will spread the interrupts around the available CPUs. pci_alloc_irq_vectors() will spread the interrupts around the available CPUs.
To get the Linux IRQ numbers passed to request_irq() and free_irq() and the To get the Linux IRQ numbers passed to request_irq() and free_irq() and the
vectors, use the following function: vectors, use the following function::
int pci_irq_vector(struct pci_dev *dev, unsigned int nr); int pci_irq_vector(struct pci_dev *dev, unsigned int nr);
Any allocated resources should be freed before removing the device using Any allocated resources should be freed before removing the device using
the following function: the following function::
void pci_free_irq_vectors(struct pci_dev *dev); void pci_free_irq_vectors(struct pci_dev *dev);
@ -126,7 +134,7 @@ The typical usage of MSI or MSI-X interrupts is to allocate as many vectors
as possible, likely up to the limit supported by the device. If nvec is as possible, likely up to the limit supported by the device. If nvec is
larger than the number supported by the device it will automatically be larger than the number supported by the device it will automatically be
capped to the supported limit, so there is no need to query the number of capped to the supported limit, so there is no need to query the number of
vectors supported beforehand: vectors supported beforehand::
nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES) nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_ALL_TYPES)
if (nvec < 0) if (nvec < 0)
@ -135,7 +143,7 @@ vectors supported beforehand:
If a driver is unable or unwilling to deal with a variable number of MSI If a driver is unable or unwilling to deal with a variable number of MSI
interrupts it can request a particular number of interrupts by passing that interrupts it can request a particular number of interrupts by passing that
number to pci_alloc_irq_vectors() function as both 'min_vecs' and number to pci_alloc_irq_vectors() function as both 'min_vecs' and
'max_vecs' parameters: 'max_vecs' parameters::
ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES); ret = pci_alloc_irq_vectors(pdev, nvec, nvec, PCI_IRQ_ALL_TYPES);
if (ret < 0) if (ret < 0)
@ -143,23 +151,24 @@ number to pci_alloc_irq_vectors() function as both 'min_vecs' and
The most notorious example of the request type described above is enabling The most notorious example of the request type described above is enabling
the single MSI mode for a device. It could be done by passing two 1s as the single MSI mode for a device. It could be done by passing two 1s as
'min_vecs' and 'max_vecs': 'min_vecs' and 'max_vecs'::
ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES); ret = pci_alloc_irq_vectors(pdev, 1, 1, PCI_IRQ_ALL_TYPES);
if (ret < 0) if (ret < 0)
goto out_err; goto out_err;
Some devices might not support using legacy line interrupts, in which case Some devices might not support using legacy line interrupts, in which case
the driver can specify that only MSI or MSI-X is acceptable: the driver can specify that only MSI or MSI-X is acceptable::
nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX); nvec = pci_alloc_irq_vectors(pdev, 1, nvec, PCI_IRQ_MSI | PCI_IRQ_MSIX);
if (nvec < 0) if (nvec < 0)
goto out_err; goto out_err;
4.3 Legacy APIs Legacy APIs
-----------
The following old APIs to enable and disable MSI or MSI-X interrupts should The following old APIs to enable and disable MSI or MSI-X interrupts should
not be used in new code: not be used in new code::
pci_enable_msi() /* deprecated */ pci_enable_msi() /* deprecated */
pci_disable_msi() /* deprecated */ pci_disable_msi() /* deprecated */
@ -174,9 +183,11 @@ number of vectors. If you have a legitimate special use case for the count
of vectors we might have to revisit that decision and add a of vectors we might have to revisit that decision and add a
pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently. pci_nr_irq_vectors() helper that handles MSI and MSI-X transparently.
4.4 Considerations when using MSIs Considerations when using MSIs
------------------------------
4.4.1 Spinlocks Spinlocks
~~~~~~~~~
Most device drivers have a per-device spinlock which is taken in the Most device drivers have a per-device spinlock which is taken in the
interrupt handler. With pin-based interrupts or a single MSI, it is not interrupt handler. With pin-based interrupts or a single MSI, it is not
@ -188,7 +199,8 @@ acquire the spinlock. Such deadlocks can be avoided by using
spin_lock_irqsave() or spin_lock_irq() which disable local interrupts spin_lock_irqsave() or spin_lock_irq() which disable local interrupts
and acquire the lock (see Documentation/kernel-hacking/locking.rst). and acquire the lock (see Documentation/kernel-hacking/locking.rst).
4.5 How to tell whether MSI/MSI-X is enabled on a device How to tell whether MSI/MSI-X is enabled on a device
----------------------------------------------------
Using 'lspci -v' (as root) may show some devices with "MSI", "Message Using 'lspci -v' (as root) may show some devices with "MSI", "Message
Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities Signalled Interrupts" or "MSI-X" capabilities. Each of these capabilities
@ -196,7 +208,8 @@ has an 'Enable' flag which is followed with either "+" (enabled)
or "-" (disabled). or "-" (disabled).
5. MSI quirks MSI quirks
==========
Several PCI chipsets or devices are known not to support MSIs. Several PCI chipsets or devices are known not to support MSIs.
The PCI stack provides three ways to disable MSIs: The PCI stack provides three ways to disable MSIs:
@ -205,7 +218,8 @@ The PCI stack provides three ways to disable MSIs:
2. on all devices behind a specific bridge 2. on all devices behind a specific bridge
3. on a single device 3. on a single device
5.1. Disabling MSIs globally Disabling MSIs globally
-----------------------
Some host chipsets simply don't support MSIs properly. If we're Some host chipsets simply don't support MSIs properly. If we're
lucky, the manufacturer knows this and has indicated it in the ACPI lucky, the manufacturer knows this and has indicated it in the ACPI
@ -219,7 +233,8 @@ on the kernel command line to disable MSIs on all devices. It would be
in your best interests to report the problem to linux-pci@vger.kernel.org in your best interests to report the problem to linux-pci@vger.kernel.org
including a full 'lspci -v' so we can add the quirks to the kernel. including a full 'lspci -v' so we can add the quirks to the kernel.
5.2. Disabling MSIs below a bridge Disabling MSIs below a bridge
-----------------------------
Some PCI bridges are not able to route MSIs between busses properly. Some PCI bridges are not able to route MSIs between busses properly.
In this case, MSIs must be disabled on all devices behind the bridge. In this case, MSIs must be disabled on all devices behind the bridge.
@ -230,7 +245,7 @@ as the nVidia nForce and Serverworks HT2000). As with host chipsets,
Linux mostly knows about them and automatically enables MSIs if it can. Linux mostly knows about them and automatically enables MSIs if it can.
If you have a bridge unknown to Linux, you can enable If you have a bridge unknown to Linux, you can enable
MSIs in configuration space using whatever method you know works, then MSIs in configuration space using whatever method you know works, then
enable MSIs on that bridge by doing: enable MSIs on that bridge by doing::
echo 1 > /sys/bus/pci/devices/$bridge/msi_bus echo 1 > /sys/bus/pci/devices/$bridge/msi_bus
@ -244,7 +259,8 @@ below this bridge.
Again, please notify linux-pci@vger.kernel.org of any bridges that need Again, please notify linux-pci@vger.kernel.org of any bridges that need
special handling. special handling.
5.3. Disabling MSIs on a single device Disabling MSIs on a single device
---------------------------------
Some devices are known to have faulty MSI implementations. Usually this Some devices are known to have faulty MSI implementations. Usually this
is handled in the individual device driver, but occasionally it's necessary is handled in the individual device driver, but occasionally it's necessary
@ -252,7 +268,8 @@ to handle this with a quirk. Some drivers have an option to disable use
of MSI. While this is a convenient workaround for the driver author, of MSI. While this is a convenient workaround for the driver author,
it is not good practice, and should not be emulated. it is not good practice, and should not be emulated.
5.4. Finding why MSIs are disabled on a device Finding why MSIs are disabled on a device
-----------------------------------------
From the above three sections, you can see that there are many reasons From the above three sections, you can see that there are many reasons
why MSIs may not be enabled for a given device. Your first step should why MSIs may not be enabled for a given device. Your first step should
@ -261,7 +278,7 @@ for your machine. You should also check your .config to be sure you
have enabled CONFIG_PCI_MSI. have enabled CONFIG_PCI_MSI.
Then, 'lspci -t' gives the list of bridges above a device. Reading Then, 'lspci -t' gives the list of bridges above a device. Reading
/sys/bus/pci/devices/*/msi_bus will tell you whether MSIs are enabled (1) `/sys/bus/pci/devices/*/msi_bus` will tell you whether MSIs are enabled (1)
or disabled (0). If 0 is found in any of the msi_bus files belonging or disabled (0). If 0 is found in any of the msi_bus files belonging
to bridges between the PCI root and the device, MSIs are disabled. to bridges between the PCI root and the device, MSIs are disabled.