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
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.
106   - override_only field defaults to 0.
110 if all the pci_device_id entries have a non-zero driver_data value.
120 --------------------------------------
128 	__exit		Exit code. Ignored for non-modular drivers.
132 	- The module_init()/module_exit() functions (and all
136 	- Do not mark the struct pci_driver.
138 	- Do NOT mark a function if you are not sure which mark to use.
171 These functions are hotplug-safe. They increment the reference count on
182   - Enable the device
183   - Request MMIO/IOP resources
184   - Set the DMA mask size (for both coherent and streaming DMA)
185   - Allocate and initialize shared control data (pci_allocate_coherent())
186   - Access device configuration space (if needed)
187   - Register IRQ handler (request_irq())
188   - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
189   - Enable DMA/processing engines.
198 ---------------------
202   - wake up the device if it was in suspended state,
203   - allocate I/O and memory regions of the device (if BIOS did not),
204   - allocate an IRQ (if BIOS did not).
226 If the PCI device can use the PCI Memory-Write-Invalidate transaction,
227 call pci_set_mwi().  This enables the PCI_COMMAND bit for Mem-Wr-Inval
230 or chip-sets may support Memory-Write-Invalidate.  Alternatively,
231 if Mem-Wr-Inval would be nice to have but is not required, call
233 Mem-Wr-Inval.
237 --------------------------
241 address by the arch/chip-set specific kernel support.
243 See Documentation/driver-api/io-mapping.rst for how to access device registers
266 ---------------------
269    Documentation/core-api/dma-api.rst. This section is just a reminder that
275 32-bit bus master capability for streaming data need the driver
280 Drivers for all PCI-X and PCIe compliant devices must call
281 dma_set_mask() as they are 64-bit DMA devices.
286 Again, this includes drivers for all PCI-X and PCIe compliant devices.
287 Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
288 64-bit DMA capable for payload ("streaming") data but not control
293 -------------------------
295 memory.  See Documentation/core-api/dma-api.rst for a full description of
301 ---------------------------
308 --------------------
320 With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
326 MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
328 The fundamental difference between MSI and MSI-X is how multiple
330 while MSI-X can allocate several individual ones.
335 capability registers. Many architectures, chip-sets, or BIOSes do NOT
336 support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
340 Drivers that have different interrupt handlers for MSI/MSI-X and
358 of MSI/MSI-X usage.
367   - Disable the device from generating IRQs
368   - Release the IRQ (free_irq())
369   - Stop all DMA activity
370   - Release DMA buffers (both streaming and coherent)
371   - Unregister from other subsystems (e.g. scsi or netdev)
372   - Disable device from responding to MMIO/IO Port addresses
373   - Release MMIO/IO Port resource(s)
377 -----------------------
391 This is another reason to use MSI or MSI-X if it's available.
392 MSI and MSI-X are defined to be exclusive interrupts and thus
397 ---------------
405 ---------------------
408 corruption, hangs, and on some chip-sets a hard crash.
418 -------------------
425 See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
429 --------------------------------
438 --------------------------------------------------------
445 --------------------------------
486 pci_set_mwi()			Enable Memory-Write-Invalidate transactions.
487 pci_clear_mwi()			Disable Memory-Write-Invalidate transactions.
500 special purposes -- on systems with multiple primary buses their semantics
518 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
519 There's a mirror of the pci.ids file at https://github.com/pciutils/pciids.
557        for (i = 8; --i; val >>= 1) {
564        for (i = 8; --i; val >>= 1) {