Documentation/PCI/pci.rst

1 .. SPDX-License-Identifier: GPL-2.0
7 :Authors: - Martin Mares <mj@ucw.cz>
8           - Grant Grundler <grundler@parisc-linux.org>
11 Since each CPU architecture implements different chip-sets and PCI devices
18 by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
26 "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
38 supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
45   - Enable the device
46   - Request MMIO/IOP resources
47   - Set the DMA mask size (for both coherent and streaming DMA)
48   - Allocate and initialize shared control data (pci_allocate_coherent())
49   - Access device configuration space (if needed)
50   - Register IRQ handler (request_irq())
51   - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
52   - Enable DMA/processing engines
57   - Disable the device from generating IRQs
58   - Release the IRQ (free_irq())
59   - Stop all DMA activity
60   - Release DMA buffers (both streaming and coherent)
61   - Unregister from other subsystems (e.g. scsi or netdev)
62   - Release MMIO/IOP resources
63   - Disable the device
81 .. kernel-doc:: include/linux/pci.h
85 all-zero entry.  Definitions with static const are generally preferred.
87 .. kernel-doc:: include/linux/mod_devicetable.h
99 All fields are passed in as hexadecimal values (no leading 0x).
103   - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
104   - class and classmask fields default to 0
105   - driver_data defaults to 0UL.
109 if all the pci_device_id entries have a non-zero driver_data value.
119 --------------------------------------
127 	__exit		Exit code. Ignored for non-modular drivers.
131 	- The module_init()/module_exit() functions (and all
135 	- Do not mark the struct pci_driver.
137 	- Do NOT mark a function if you are not sure which mark to use.
170 These functions are hotplug-safe. They increment the reference count on
181   - Enable the device
182   - Request MMIO/IOP resources
183   - Set the DMA mask size (for both coherent and streaming DMA)
184   - Allocate and initialize shared control data (pci_allocate_coherent())
185   - Access device configuration space (if needed)
186   - Register IRQ handler (request_irq())
187   - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
188   - Enable DMA/processing engines.
197 ---------------------
201   - wake up the device if it was in suspended state,
202   - allocate I/O and memory regions of the device (if BIOS did not),
203   - allocate an IRQ (if BIOS did not).
225 If the PCI device can use the PCI Memory-Write-Invalidate transaction,
226 call pci_set_mwi().  This enables the PCI_COMMAND bit for Mem-Wr-Inval
229 or chip-sets may support Memory-Write-Invalidate.  Alternatively,
230 if Mem-Wr-Inval would be nice to have but is not required, call
232 Mem-Wr-Inval.
236 --------------------------
240 address by the arch/chip-set specific kernel support.
242 See Documentation/driver-api/io-mapping.rst for how to access device registers
265 ---------------------
268    :doc:`/core-api/dma-api`. This section is just a reminder that
274 32-bit bus master capability for streaming data need the driver
279 Drivers for all PCI-X and PCIe compliant devices must call
280 pci_set_dma_mask() as they are 64-bit DMA devices.
285 Again, this includes drivers for all PCI-X and PCIe compliant devices.
286 Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
287 64-bit DMA capable for payload ("streaming") data but not control
292 -------------------------
294 memory.  See :doc:`/core-api/dma-api` for a full description of
300 ---------------------------
307 --------------------
319 With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
325 MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
327 The fundamental difference between MSI and MSI-X is how multiple
328 "vectors" get allocated. MSI requires contiguous blocks of vectors
329 while MSI-X can allocate several individual ones.
331 MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
334 capability registers. Many architectures, chip-sets, or BIOSes do NOT
335 support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
339 Drivers that have different interrupt handlers for MSI/MSI-X and
344 There are (at least) two really good reasons for using MSI:
346 1) MSI is an exclusive interrupt vector by definition.
350 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
351    to be visible to the host CPU(s) when the MSI is delivered. This
357 of MSI/MSI-X usage.
366   - Disable the device from generating IRQs
367   - Release the IRQ (free_irq())
368   - Stop all DMA activity
369   - Release DMA buffers (both streaming and consistent)
370   - Unregister from other subsystems (e.g. scsi or netdev)
371   - Disable device from responding to MMIO/IO Port addresses
372   - Release MMIO/IO Port resource(s)
376 -----------------------
390 This is another reason to use MSI or MSI-X if it's available.
391 MSI and MSI-X are defined to be exclusive interrupts and thus
396 ---------------
404 ---------------------
407 corruption, hangs, and on some chip-sets a hard crash.
417 -------------------
424 See :doc:`/core-api/dma-api` for details on unmapping interfaces.
428 --------------------------------
437 --------------------------------------------------------
444 --------------------------------
485 pci_set_mwi()			Enable Memory-Write-Invalidate transactions.
486 pci_clear_mwi()			Disable Memory-Write-Invalidate transactions.
499 special purposes -- on systems with multiple primary buses their semantics
517 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
556        for (i = 8; --i; val >>= 1) {
563        for (i = 8; --i; val >>= 1) {