Lines Matching +full:dma +full:- +full:shared +full:- +full:all
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
14 tries to introduce all potential driver authors to Linux APIs for
18 by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
22 However, keep in mind that all documents are subject to "bit rot".
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
99 All fields are passed in as hexadecimal values (no leading 0x).
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.
116 automatically calls the remove hook for all devices handled by the driver.
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
229 Check the return value of pci_set_mwi() as not all architectures
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
292 Setup shared control data
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 --------------------
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
315 can be shared).
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 -----------------------
380 the IRQ is shared with another device.
382 When the shared IRQ handler is "unhooked", the remaining devices
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
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 --------------------------------
454 space of a device represented by `struct pci_dev *`. All these functions return
486 pci_set_mwi() Enable Memory-Write-Invalidate transactions.
487 pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
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
512 are shared across multiple drivers. You can add private definitions in
518 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
557 for (i = 8; --i; val >>= 1) {
564 for (i = 8; --i; val >>= 1) {
575 handle the PCI master abort on all platforms if the PCI device is