Documentation/PCI/pci.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 How To Write Linux PCI Drivers
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).
221 pci_set_master() will enable DMA by setting the bus master bit
224 disable DMA by clearing the bus master bit.
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
265 Set the DMA mask size
266 ---------------------
269    Documentation/core-api/dma-api.rst. This section is just a reminder that
270    drivers need to indicate DMA capabilities of the device and is not
271    an authoritative source for DMA interfaces.
273 While all drivers should explicitly indicate the DMA capability
275 32-bit bus master capability for streaming data need the driver
277 appropriate parameters.  In general this allows more efficient DMA
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 -------------------------
294 Once the DMA masks are set, the driver can allocate "coherent" (a.k.a. shared)
295 memory.  See Documentation/core-api/dma-api.rst for a full description of
296 the DMA APIs. This section is just a reminder that it needs to be done
297 before enabling DMA on the device.
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"
327 which deliver interrupts to the CPU via a DMA write to a Local APIC.
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
351 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
355    the DMA stream.
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 ---------------
404 Stop all DMA activity
405 ---------------------
406 It's extremely important to stop all DMA operations BEFORE attempting
407 to deallocate DMA control data. Failure to do so can result in memory
408 corruption, hangs, and on some chip-sets a hard crash.
410 Stopping DMA after stopping the IRQs can avoid races where the
411 IRQ handler might restart DMA engines.
417 Release DMA buffers
418 -------------------
419 Once DMA is stopped, clean up streaming DMA first.
425 See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
429 --------------------------------
438 --------------------------------------------------------
445 --------------------------------
453 You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
460 `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
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/.
541 MMIO Space and "Write Posting"
545 often requires some additional changes. Specifically, "write posting"
547 already do this. I/O Port space guarantees write transactions reach the PCI
550 call this "Write Posting" because the write completion is "posted" to
557        for (i = 8; --i; val >>= 1) {
558                outb(val & 1, ioport_reg);      /* write bit */
564        for (i = 8; --i; val >>= 1) {
565                writeb(val & 1, mmio_reg);      /* write bit */
566                readb(safe_mmio_reg);           /* flush posted write */