Lines Matching +full:irq +full:- +full:device
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
15 PCI device drivers.
17 A more complete resource is the third edition of "Linux Device Drivers"
18 by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
26 "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
33 a new device, the driver with a matching "description" will be notified.
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
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,
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
77 PCI device drivers call ``pci_register_driver()`` during their
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
93 New PCI IDs may be added to a device driver pci_ids table at runtime
96 echo "vendor device subvendor subdevice class class_mask driver_data" > \
100 The vendor and device fields are mandatory, the others are optional. Users
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.
148 is because one PCI device implements several different HW services.
153 Searching by vendor and device ID::
163 Searching by both vendor/device and subsystem vendor/device ID::
168 VENDOR_ID or DEVICE_ID. This allows searching for any device from a
171 These functions are hotplug-safe. They increment the reference count on
176 Device Initialization Steps
180 for device initialization:
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.
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).
213 Currently, the device drivers can't detect the bug when two
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 --------------------------
239 from the PCI device config space. Use the values in the pci_dev structure
241 address by the arch/chip-set specific kernel support.
243 See Documentation/driver-api/io-mapping.rst for how to access device registers
244 or device memory.
246 The device driver needs to call pci_request_region() to verify
247 no other device is already using the same address resource.
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
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.
283 Similarly, drivers must also "register" this capability if the device
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
297 before enabling DMA on the device.
300 Initialize device registers
301 ---------------------------
307 Register IRQ handler
308 --------------------
310 this is often just another intermediate step to initialize a device.
311 This step can often be deferred until the device is opened for use.
313 All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
314 and use the devid to map IRQs to devices (remember that all PCI IRQ lines
317 request_irq() will associate an interrupt handler and device handle
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".
322 request_irq() also enables the interrupt. Make sure the device is
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.
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
340 Drivers that have different interrupt handlers for MSI/MSI-X and
349 its device caused the interrupt.
351 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
358 of MSI/MSI-X usage.
361 PCI device shutdown
364 When a PCI device driver is being unloaded, most of the following
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)
376 Stop IRQs on the device
377 -----------------------
378 How to do this is chip/device specific. If it's not done, it opens
380 the IRQ is shared with another device.
382 When the shared IRQ handler is "unhooked", the remaining devices
383 using the same IRQ line will still need the IRQ enabled. Thus if the
384 "unhooked" device asserts IRQ line, the system will respond assuming
385 it was one of the remaining devices asserted the IRQ line. Since none
386 of the other devices will handle the IRQ, the system will "hang" until
387 it decides the IRQ isn't going to get handled and masks the IRQ (100,000
388 iterations later). Once the shared IRQ is masked, the remaining devices
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
396 Release the IRQ
397 ---------------
398 Once the device is quiesced (no more IRQs), one can call free_irq().
400 "unhook" the drivers IRQ handler from that IRQ, and finally release
401 the IRQ if no one else is using it.
405 ---------------------
408 corruption, hangs, and on some chip-sets a hard crash.
411 IRQ handler might restart DMA engines.
418 -------------------
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
437 Disable Device from responding to MMIO/IO Port addresses
438 --------------------------------------------------------
441 Do not access device registers after calling pci_disable_device().
445 --------------------------------
454 space of a device represented by `struct pci_dev *`. All these functions return
460 `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
476 bus and slot and number. If the device is
479 pci_find_capability() Find specified capability in device's capability
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
500 special purposes -- on systems with multiple primary buses their semantics
508 Vendor and device identifications
511 Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
515 The device IDs are arbitrary hex numbers (vendor controlled) and normally used
518 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
537 The alternative is the traditional PCI device driver that walks PCI
538 device lists. This is still possible but discouraged.
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
557 for (i = 8; --i; val >>= 1) {
564 for (i = 8; --i; val >>= 1) {
571 interferes with the correct operation of the device.
573 Another case to watch out for is when resetting a PCI device. Use PCI
575 handle the PCI master abort on all platforms if the PCI device is