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.
109 if all the pci_device_id entries have a non-zero driver_data value.
115 automatically calls the remove hook for all devices handled by the driver.
119 --------------------------------------
127 __exit Exit code. Ignored for non-modular drivers.
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.
170 These functions are hotplug-safe. They increment the reference count on
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.
197 ---------------------
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).
220 pci_set_master() will enable DMA by setting the bus master bit
223 disable DMA by clearing the bus master bit.
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
228 Check the return value of pci_set_mwi() as not all architectures
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
232 Mem-Wr-Inval.
236 --------------------------
240 address by the arch/chip-set specific kernel support.
242 See Documentation/driver-api/io-mapping.rst for how to access device registers
264 Set the DMA mask size
265 ---------------------
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
270 an authoritative source for DMA interfaces.
272 While all drivers should explicitly indicate the DMA capability
274 32-bit bus master capability for streaming data need the driver
276 appropriate parameters. In general this allows more efficient DMA
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
291 Setup shared control data
292 -------------------------
293 Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
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
296 before enabling DMA on the device.
300 ---------------------------
307 --------------------
312 All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
313 and use the devid to map IRQs to devices (remember that all PCI IRQ lines
314 can be shared).
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.
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
339 Drivers that have different interrupt handlers for MSI/MSI-X and
350 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
354 the DMA stream.
357 of MSI/MSI-X usage.
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 -----------------------
379 the IRQ is shared with another device.
381 When the shared IRQ handler is "unhooked", the remaining devices
387 iterations later). Once the shared IRQ is masked, the remaining devices
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
396 ---------------
403 Stop all DMA activity
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.
409 Stopping DMA after stopping the IRQs can avoid races where the
410 IRQ handler might restart DMA engines.
416 Release DMA buffers
417 -------------------
418 Once DMA is stopped, clean up streaming DMA first.
424 See :doc:`/core-api/dma-api` for details on unmapping interfaces.
428 --------------------------------
437 --------------------------------------------------------
444 --------------------------------
453 space of a device represented by `struct pci_dev *`. All these functions return
485 pci_set_mwi() Enable Memory-Write-Invalidate transactions.
486 pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
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
511 are shared across multiple drivers. You can add private definitions in
517 Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
556 for (i = 8; --i; val >>= 1) {
563 for (i = 8; --i; val >>= 1) {
574 handle the PCI master abort on all platforms if the PCI device is