Lines Matching +full:pci +full:- +full:to +full:- +full:cpu
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>
10 The world of PCI is vast and full of (mostly unpleasant) surprises.
11 Since each CPU architecture implements different chip-sets and PCI devices
12 have different requirements (erm, "features"), the result is the PCI support
14 tries to introduce all potential driver authors to Linux APIs for
15 PCI device drivers.
18 by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
22 However, keep in mind that all documents are subject to "bit rot".
23 Refer to the source code if things are not working as described here.
25 Please send questions/comments/patches about Linux PCI API to the
26 "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
29 Structure of PCI drivers
31 PCI drivers "discover" PCI devices in a system via pci_register_driver().
32 Actually, it's the other way around. When the PCI generic code discovers
36 pci_register_driver() leaves most of the probing for devices to
37 the PCI layer and supports online insertion/removal of devices [thus
38 supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
42 Once the driver knows about a PCI device and takes ownership, the
43 driver generally needs to perform the following initialization:
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
54 When done using the device, and perhaps the module needs to be unloaded,
55 the driver needs to take the follow steps:
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
66 For the rest look at LDD3 or <linux/pci.h> .
68 If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
69 the PCI functions described below are defined as inline functions either
70 completely empty or just returning an appropriate error codes to avoid
77 PCI device drivers call ``pci_register_driver()`` during their
78 initialization with a pointer to a structure describing the driver
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
90 Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
93 New PCI IDs may be added to a device driver pci_ids table at runtime
97 /sys/bus/pci/drivers/{driver}/new_id
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.
112 PCI devices listed in its (newly updated) pci_ids list.
114 When the driver exits, it just calls pci_unregister_driver() and the PCI layer
119 --------------------------------------
127 __exit Exit code. Ignored for non-modular drivers.
130 Tips on when/where to use the above attributes:
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.
138 Better to not mark the function than mark the function wrong.
141 How to find PCI devices manually
144 PCI drivers should have a really good reason for not using the
145 pci_register_driver() interface to search for PCI devices.
146 The main reason PCI devices are controlled by multiple drivers
147 is because one PCI device implements several different HW services.
170 These functions are hotplug-safe. They increment the reference count on
178 As noted in the introduction, most PCI drivers need the following steps
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.
190 The driver can access PCI config space registers at any time.
192 that will just result in a PCI Bus Master Abort and config reads
196 Enable the PCI device
197 ---------------------
198 Before touching any device registers, the driver needs to enable
199 the PCI device by calling pci_enable_device(). This will:
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).
214 problem and unlikely to get fixed soon.
222 it's set to something bogus by the BIOS. pci_clear_master() will
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
231 pci_try_set_mwi() to have the system do its best effort at enabling
232 Mem-Wr-Inval.
236 --------------------------
238 from the PCI device config space. Use the values in the pci_dev structure
239 as the PCI "bus address" might have been remapped to a "host physical"
240 address by the arch/chip-set specific kernel support.
242 See Documentation/driver-api/io-mapping.rst for how to access device registers
245 The device driver needs to call pci_request_region() to verify
249 The idea is to prevent two devices colliding on the same address range.
258 Use these for address resources that are not described by "normal" PCI
265 ---------------------
267 If anything below doesn't make sense, please refer to
268 :doc:`/core-api/dma-api`. This section is just a reminder that
269 drivers need to indicate DMA capabilities of the device and is not
273 (e.g. 32 or 64 bit) of the PCI bus master, devices with more than
274 32-bit bus master capability for streaming data need the driver
275 to "register" this capability by calling pci_set_dma_mask() with
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
295 the DMA APIs. This section is just a reminder that it needs to be done
300 ---------------------------
307 --------------------
309 this is often just another intermediate step to initialize a device.
313 and use the devid to map IRQs to devices (remember that all PCI IRQ lines
318 IRQ lines which run from the PCI device to the Interrupt controller.
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"
326 which deliver interrupts to the CPU via a DMA write to a Local APIC.
327 The fundamental difference between MSI and MSI-X is how multiple
329 while MSI-X can allocate several individual ones.
333 causes the PCI support to program CPU vector data into the PCI device
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
336 the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
339 Drivers that have different interrupt handlers for MSI/MSI-X and
347 This means the interrupt handler doesn't have to verify
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
353 This guarantee allows the driver to omit MMIO reads to flush
357 of MSI/MSI-X usage.
360 PCI device shutdown
363 When a PCI device driver is being unloaded, most of the following
364 steps need to be performed:
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 -----------------------
377 How to do this is chip/device specific. If it's not done, it opens
386 it decides the IRQ isn't going to get handled and masks the IRQ (100,000
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
392 are not susceptible to the "screaming interrupt" problem.
396 ---------------
404 ---------------------
405 It's extremely important to stop all DMA operations BEFORE attempting
406 to deallocate DMA control data. Failure to do so can result in memory
407 corruption, hangs, and on some chip-sets a hard crash.
417 -------------------
419 I.e. unmap data buffers and return buffers to "upstream"
424 See :doc:`/core-api/dma-api` for details on unmapping interfaces.
428 --------------------------------
429 Most low level PCI device drivers support some other subsystem
433 the subsystem attempts to call into a driver that has been unloaded.
436 Disable Device from responding to MMIO/IO Port addresses
437 --------------------------------------------------------
444 --------------------------------
445 Call pci_release_region() to mark the MMIO or IO Port range as available.
446 Failure to do so usually results in the inability to reload the driver.
449 How to access PCI config space
452 You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
454 0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
455 text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
459 `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
463 use symbolic names of locations and bits declared in <linux/pci.h>.
465 If you need to access Extended PCI Capability registers, just call
474 pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
477 pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
480 pci_resource_start() Returns bus start address for a given PCI region
481 pci_resource_end() Returns bus end address for a given PCI region
482 pci_resource_len() Returns the byte length of a PCI region
485 pci_set_mwi() Enable Memory-Write-Invalidate transactions.
486 pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
493 When displaying PCI device names to the user (for example when a driver wants
494 to tell the user what card has it found), please use pci_name(pci_dev).
496 Always refer to the PCI devices by a pointer to the pci_dev structure.
497 All PCI layer functions use this identification and it's the only
499 special purposes -- on systems with multiple primary buses their semantics
502 Don't try to turn on Fast Back to Back writes in your driver. All devices
503 on the bus need to be capable of doing it, so this is something which needs
504 to be handled by platform and generic code, not individual drivers.
510 Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
517 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
518 There's a mirror of the pci.ids file at https://github.com/pciutils/pciids.
524 There are several functions which you might come across when trying to
525 port an old driver to the new PCI interface. They are no longer present
526 in the kernel as they aren't compatible with hotplug or PCI domains or
536 The alternative is the traditional PCI device driver that walks PCI
543 Converting a driver from using I/O Port space to using MMIO space
545 needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
546 already do this. I/O Port space guarantees write transactions reach the PCI
547 device before the CPU can continue. Writes to MMIO space allow the CPU
548 to continue before the transaction reaches the PCI device. HW weenies
549 call this "Write Posting" because the write completion is "posted" to
550 the CPU before the transaction has reached its destination.
552 Thus, timing sensitive code should add readl() where the CPU is
553 expected to wait before doing other work. The classic "bit banging"
556 for (i = 8; --i; val >>= 1) {
563 for (i = 8; --i; val >>= 1) {
572 Another case to watch out for is when resetting a PCI device. Use PCI
573 Configuration space reads to flush the writel(). This will gracefully
574 handle the PCI master abort on all platforms if the PCI device is
575 expected to not respond to a readl(). Most x86 platforms will allow
576 MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage