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.
106 - override_only field defaults to 0.
110 if all the pci_device_id entries have a non-zero driver_data value.
113 PCI devices listed in its (newly updated) pci_ids list.
115 When the driver exits, it just calls pci_unregister_driver() and the PCI layer
120 --------------------------------------
128 __exit Exit code. Ignored for non-modular drivers.
131 Tips on when/where to use the above attributes:
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.
139 Better to not mark the function than mark the function wrong.
142 How to find PCI devices manually
145 PCI drivers should have a really good reason for not using the
146 pci_register_driver() interface to search for PCI devices.
147 The main reason PCI devices are controlled by multiple drivers
148 is because one PCI device implements several different HW services.
171 These functions are hotplug-safe. They increment the reference count on
179 As noted in the introduction, most PCI drivers need the following steps
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.
191 The driver can access PCI config space registers at any time.
193 that will just result in a PCI Bus Master Abort and config reads
197 Enable the PCI device
198 ---------------------
199 Before touching any device registers, the driver needs to enable
200 the PCI device by calling pci_enable_device(). This will:
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).
215 problem and unlikely to get fixed soon.
223 it's set to something bogus by the BIOS. pci_clear_master() will
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
232 pci_try_set_mwi() to have the system do its best effort at enabling
233 Mem-Wr-Inval.
237 --------------------------
239 from the PCI device config space. Use the values in the pci_dev structure
240 as the PCI "bus address" might have been remapped to a "host physical"
241 address by the arch/chip-set specific kernel support.
243 See Documentation/driver-api/io-mapping.rst for how to access device registers
246 The device driver needs to call pci_request_region() to verify
250 The idea is to prevent two devices colliding on the same address range.
259 Use these for address resources that are not described by "normal" PCI
266 ---------------------
268 If anything below doesn't make sense, please refer to
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
274 (e.g. 32 or 64 bit) of the PCI bus master, devices with more than
275 32-bit bus master capability for streaming data need the driver
276 to "register" this capability by calling dma_set_mask() with
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
296 the DMA APIs. This section is just a reminder that it needs to be done
301 ---------------------------
308 --------------------
310 this is often just another intermediate step to initialize a device.
314 and use the devid to map IRQs to devices (remember that all PCI IRQ lines
319 IRQ lines which run from the PCI device to the Interrupt controller.
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.
334 causes the PCI support to program CPU vector data into the PCI device
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
337 the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
340 Drivers that have different interrupt handlers for MSI/MSI-X and
348 This means the interrupt handler doesn't have to verify
351 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
352 to be visible to the host CPU(s) when the MSI is delivered. This
354 This guarantee allows the driver to omit MMIO reads to flush
358 of MSI/MSI-X usage.
361 PCI device shutdown
364 When a PCI device driver is being unloaded, most of the following
365 steps need to be performed:
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 -----------------------
378 How to do this is chip/device specific. If it's not done, it opens
387 it decides the IRQ isn't going to get handled and masks the IRQ (100,000
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
393 are not susceptible to the "screaming interrupt" problem.
397 ---------------
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.
418 -------------------
420 I.e. unmap data buffers and return buffers to "upstream"
425 See Documentation/core-api/dma-api.rst for details on unmapping interfaces.
429 --------------------------------
430 Most low level PCI device drivers support some other subsystem
434 the subsystem attempts to call into a driver that has been unloaded.
437 Disable Device from responding to MMIO/IO Port addresses
438 --------------------------------------------------------
445 --------------------------------
446 Call pci_release_region() to mark the MMIO or IO Port range as available.
447 Failure to do so usually results in the inability to reload the driver.
450 How to access PCI config space
453 You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
455 0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
456 text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
460 `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
464 use symbolic names of locations and bits declared in <linux/pci.h>.
466 If you need to access Extended PCI Capability registers, just call
475 pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
478 pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
481 pci_resource_start() Returns bus start address for a given PCI region
482 pci_resource_end() Returns bus end address for a given PCI region
483 pci_resource_len() Returns the byte length of a PCI region
486 pci_set_mwi() Enable Memory-Write-Invalidate transactions.
487 pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
494 When displaying PCI device names to the user (for example when a driver wants
495 to tell the user what card has it found), please use pci_name(pci_dev).
497 Always refer to the PCI devices by a pointer to the pci_dev structure.
498 All PCI layer functions use this identification and it's the only
500 special purposes -- on systems with multiple primary buses their semantics
503 Don't try to turn on Fast Back to Back writes in your driver. All devices
504 on the bus need to be capable of doing it, so this is something which needs
505 to be handled by platform and generic code, not individual drivers.
511 Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
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.
525 There are several functions which you might come across when trying to
526 port an old driver to the new PCI interface. They are no longer present
527 in the kernel as they aren't compatible with hotplug or PCI domains or
537 The alternative is the traditional PCI device driver that walks PCI
544 Converting a driver from using I/O Port space to using MMIO space
546 needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
547 already do this. I/O Port space guarantees write transactions reach the PCI
548 device before the CPU can continue. Writes to MMIO space allow the CPU
549 to continue before the transaction reaches the PCI device. HW weenies
550 call this "Write Posting" because the write completion is "posted" to
551 the CPU before the transaction has reached its destination.
553 Thus, timing sensitive code should add readl() where the CPU is
554 expected to wait before doing other work. The classic "bit banging"
557 for (i = 8; --i; val >>= 1) {
564 for (i = 8; --i; val >>= 1) {
573 Another case to watch out for is when resetting a PCI device. Use PCI
574 Configuration space reads to flush the writel(). This will gracefully
575 handle the PCI master abort on all platforms if the PCI device is
576 expected to not respond to a readl(). Most x86 platforms will allow
577 MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage