2019-05-14 22:47:24 +08:00
|
|
|
.. SPDX-License-Identifier: GPL-2.0
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
==============================
|
|
|
|
How To Write Linux PCI Drivers
|
|
|
|
==============================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
:Authors: - Martin Mares <mj@ucw.cz>
|
|
|
|
- Grant Grundler <grundler@parisc-linux.org>
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
The world of PCI is vast and full of (mostly unpleasant) surprises.
|
|
|
|
Since each CPU architecture implements different chip-sets and PCI devices
|
|
|
|
have different requirements (erm, "features"), the result is the PCI support
|
|
|
|
in the Linux kernel is not as trivial as one would wish. This short paper
|
|
|
|
tries to introduce all potential driver authors to Linux APIs for
|
|
|
|
PCI device drivers.
|
|
|
|
|
|
|
|
A more complete resource is the third edition of "Linux Device Drivers"
|
|
|
|
by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
|
|
|
|
LDD3 is available for free (under Creative Commons License) from:
|
2019-05-14 22:47:24 +08:00
|
|
|
http://lwn.net/Kernel/LDD3/.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
However, keep in mind that all documents are subject to "bit rot".
|
|
|
|
Refer to the source code if things are not working as described here.
|
|
|
|
|
|
|
|
Please send questions/comments/patches about Linux PCI API to the
|
|
|
|
"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
|
|
|
|
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Structure of PCI drivers
|
|
|
|
========================
|
2006-12-25 16:06:35 +08:00
|
|
|
PCI drivers "discover" PCI devices in a system via pci_register_driver().
|
|
|
|
Actually, it's the other way around. When the PCI generic code discovers
|
|
|
|
a new device, the driver with a matching "description" will be notified.
|
|
|
|
Details on this below.
|
|
|
|
|
|
|
|
pci_register_driver() leaves most of the probing for devices to
|
|
|
|
the PCI layer and supports online insertion/removal of devices [thus
|
|
|
|
supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
|
|
|
|
pci_register_driver() call requires passing in a table of function
|
|
|
|
pointers and thus dictates the high level structure of a driver.
|
|
|
|
|
|
|
|
Once the driver knows about a PCI device and takes ownership, the
|
|
|
|
driver generally needs to perform the following initialization:
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- Enable the device
|
|
|
|
- Request MMIO/IOP resources
|
|
|
|
- Set the DMA mask size (for both coherent and streaming DMA)
|
|
|
|
- Allocate and initialize shared control data (pci_allocate_coherent())
|
|
|
|
- Access device configuration space (if needed)
|
|
|
|
- Register IRQ handler (request_irq())
|
|
|
|
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
|
|
|
- Enable DMA/processing engines
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
When done using the device, and perhaps the module needs to be unloaded,
|
|
|
|
the driver needs to take the follow steps:
|
2019-05-14 22:47:24 +08:00
|
|
|
|
|
|
|
- Disable the device from generating IRQs
|
|
|
|
- Release the IRQ (free_irq())
|
|
|
|
- Stop all DMA activity
|
|
|
|
- Release DMA buffers (both streaming and coherent)
|
|
|
|
- Unregister from other subsystems (e.g. scsi or netdev)
|
|
|
|
- Release MMIO/IOP resources
|
|
|
|
- Disable the device
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
Most of these topics are covered in the following sections.
|
|
|
|
For the rest look at LDD3 or <linux/pci.h> .
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
|
2006-12-25 16:06:35 +08:00
|
|
|
the PCI functions described below are defined as inline functions either
|
|
|
|
completely empty or just returning an appropriate error codes to avoid
|
|
|
|
lots of ifdefs in the drivers.
|
|
|
|
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
pci_register_driver() call
|
|
|
|
==========================
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
PCI device drivers call ``pci_register_driver()`` during their
|
2006-12-25 16:06:35 +08:00
|
|
|
initialization with a pointer to a structure describing the driver
|
2019-05-14 22:47:24 +08:00
|
|
|
(``struct pci_driver``):
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
.. kernel-doc:: include/linux/pci.h
|
|
|
|
:functions: pci_driver
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
The ID table is an array of ``struct pci_device_id`` entries ending with an
|
|
|
|
all-zero entry. Definitions with static const are generally preferred.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
.. kernel-doc:: include/linux/mod_devicetable.h
|
|
|
|
:functions: pci_device_id
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
|
2006-12-25 16:06:35 +08:00
|
|
|
a pci_device_id table.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
New PCI IDs may be added to a device driver pci_ids table at runtime
|
2019-05-14 22:47:24 +08:00
|
|
|
as shown below::
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
echo "vendor device subvendor subdevice class class_mask driver_data" > \
|
|
|
|
/sys/bus/pci/drivers/{driver}/new_id
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
All fields are passed in as hexadecimal values (no leading 0x).
|
2007-04-07 23:21:28 +08:00
|
|
|
The vendor and device fields are mandatory, the others are optional. Users
|
|
|
|
need pass only as many optional fields as necessary:
|
2019-05-14 22:47:24 +08:00
|
|
|
|
|
|
|
- subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
|
|
|
|
- class and classmask fields default to 0
|
|
|
|
- driver_data defaults to 0UL.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2008-08-18 03:06:59 +08:00
|
|
|
Note that driver_data must match the value used by any of the pci_device_id
|
|
|
|
entries defined in the driver. This makes the driver_data field mandatory
|
|
|
|
if all the pci_device_id entries have a non-zero driver_data value.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
Once added, the driver probe routine will be invoked for any unclaimed
|
|
|
|
PCI devices listed in its (newly updated) pci_ids list.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
When the driver exits, it just calls pci_unregister_driver() and the PCI layer
|
|
|
|
automatically calls the remove hook for all devices handled by the driver.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
"Attributes" for driver functions/data
|
|
|
|
--------------------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2005-04-17 06:20:36 +08:00
|
|
|
Please mark the initialization and cleanup functions where appropriate
|
|
|
|
(the corresponding macros are defined in <linux/init.h>):
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
====== =================================================
|
2005-04-17 06:20:36 +08:00
|
|
|
__init Initialization code. Thrown away after the driver
|
|
|
|
initializes.
|
|
|
|
__exit Exit code. Ignored for non-modular drivers.
|
2019-05-14 22:47:24 +08:00
|
|
|
====== =================================================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
Tips on when/where to use the above attributes:
|
2019-05-14 22:47:24 +08:00
|
|
|
- The module_init()/module_exit() functions (and all
|
2006-12-25 16:06:35 +08:00
|
|
|
initialization functions called _only_ from these)
|
|
|
|
should be marked __init/__exit.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- Do not mark the struct pci_driver.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- Do NOT mark a function if you are not sure which mark to use.
|
2006-12-25 16:06:35 +08:00
|
|
|
Better to not mark the function than mark the function wrong.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
How to find PCI devices manually
|
|
|
|
================================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
PCI drivers should have a really good reason for not using the
|
|
|
|
pci_register_driver() interface to search for PCI devices.
|
|
|
|
The main reason PCI devices are controlled by multiple drivers
|
|
|
|
is because one PCI device implements several different HW services.
|
|
|
|
E.g. combined serial/parallel port/floppy controller.
|
|
|
|
|
|
|
|
A manual search may be performed using the following constructs:
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Searching by vendor and device ID::
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
struct pci_dev *dev = NULL;
|
|
|
|
while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
|
|
|
|
configure_device(dev);
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Searching by class ID (iterate in a similar way)::
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
pci_get_class(CLASS_ID, dev)
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Searching by both vendor/device and subsystem vendor/device ID::
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
You can use the constant PCI_ANY_ID as a wildcard replacement for
|
2005-04-17 06:20:36 +08:00
|
|
|
VENDOR_ID or DEVICE_ID. This allows searching for any device from a
|
|
|
|
specific vendor, for example.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
These functions are hotplug-safe. They increment the reference count on
|
2005-04-17 06:20:36 +08:00
|
|
|
the pci_dev that they return. You must eventually (possibly at module unload)
|
|
|
|
decrement the reference count on these devices by calling pci_dev_put().
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Device Initialization Steps
|
|
|
|
===========================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
As noted in the introduction, most PCI drivers need the following steps
|
|
|
|
for device initialization:
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- Enable the device
|
|
|
|
- Request MMIO/IOP resources
|
|
|
|
- Set the DMA mask size (for both coherent and streaming DMA)
|
|
|
|
- Allocate and initialize shared control data (pci_allocate_coherent())
|
|
|
|
- Access device configuration space (if needed)
|
|
|
|
- Register IRQ handler (request_irq())
|
|
|
|
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
|
|
|
- Enable DMA/processing engines.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
The driver can access PCI config space registers at any time.
|
|
|
|
(Well, almost. When running BIST, config space can go away...but
|
|
|
|
that will just result in a PCI Bus Master Abort and config reads
|
|
|
|
will return garbage).
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Enable the PCI device
|
|
|
|
---------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Before touching any device registers, the driver needs to enable
|
|
|
|
the PCI device by calling pci_enable_device(). This will:
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- wake up the device if it was in suspended state,
|
|
|
|
- allocate I/O and memory regions of the device (if BIOS did not),
|
|
|
|
- allocate an IRQ (if BIOS did not).
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
.. note::
|
|
|
|
pci_enable_device() can fail! Check the return value.
|
|
|
|
|
|
|
|
.. warning::
|
|
|
|
OS BUG: we don't check resource allocations before enabling those
|
|
|
|
resources. The sequence would make more sense if we called
|
|
|
|
pci_request_resources() before calling pci_enable_device().
|
|
|
|
Currently, the device drivers can't detect the bug when when two
|
|
|
|
devices have been allocated the same range. This is not a common
|
|
|
|
problem and unlikely to get fixed soon.
|
|
|
|
|
|
|
|
This has been discussed before but not changed as of 2.6.19:
|
|
|
|
http://lkml.org/lkml/2006/3/2/194
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
|
|
|
|
pci_set_master() will enable DMA by setting the bus master bit
|
|
|
|
in the PCI_COMMAND register. It also fixes the latency timer value if
|
2008-12-23 11:08:29 +08:00
|
|
|
it's set to something bogus by the BIOS. pci_clear_master() will
|
|
|
|
disable DMA by clearing the bus master bit.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
If the PCI device can use the PCI Memory-Write-Invalidate transaction,
|
2005-04-17 06:20:36 +08:00
|
|
|
call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
|
|
|
|
and also ensures that the cache line size register is set correctly.
|
2006-12-25 16:06:35 +08:00
|
|
|
Check the return value of pci_set_mwi() as not all architectures
|
2007-07-10 02:55:54 +08:00
|
|
|
or chip-sets may support Memory-Write-Invalidate. Alternatively,
|
|
|
|
if Mem-Wr-Inval would be nice to have but is not required, call
|
|
|
|
pci_try_set_mwi() to have the system do its best effort at enabling
|
|
|
|
Mem-Wr-Inval.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Request MMIO/IOP resources
|
|
|
|
--------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Memory (MMIO), and I/O port addresses should NOT be read directly
|
|
|
|
from the PCI device config space. Use the values in the pci_dev structure
|
|
|
|
as the PCI "bus address" might have been remapped to a "host physical"
|
|
|
|
address by the arch/chip-set specific kernel support.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2011-08-15 08:02:26 +08:00
|
|
|
See Documentation/io-mapping.txt for how to access device registers
|
2006-12-25 16:06:35 +08:00
|
|
|
or device memory.
|
|
|
|
|
|
|
|
The device driver needs to call pci_request_region() to verify
|
|
|
|
no other device is already using the same address resource.
|
|
|
|
Conversely, drivers should call pci_release_region() AFTER
|
2005-04-17 06:20:36 +08:00
|
|
|
calling pci_disable_device().
|
2006-12-25 16:06:35 +08:00
|
|
|
The idea is to prevent two devices colliding on the same address range.
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
.. tip::
|
|
|
|
See OS BUG comment above. Currently (2.6.19), The driver can only
|
|
|
|
determine MMIO and IO Port resource availability _after_ calling
|
|
|
|
pci_enable_device().
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
Generic flavors of pci_request_region() are request_mem_region()
|
|
|
|
(for MMIO ranges) and request_region() (for IO Port ranges).
|
|
|
|
Use these for address resources that are not described by "normal" PCI
|
|
|
|
BARs.
|
|
|
|
|
|
|
|
Also see pci_request_selected_regions() below.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Set the DMA mask size
|
|
|
|
---------------------
|
|
|
|
.. note::
|
|
|
|
If anything below doesn't make sense, please refer to
|
|
|
|
Documentation/DMA-API.txt. This section is just a reminder that
|
|
|
|
drivers need to indicate DMA capabilities of the device and is not
|
|
|
|
an authoritative source for DMA interfaces.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
While all drivers should explicitly indicate the DMA capability
|
|
|
|
(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
|
|
|
|
32-bit bus master capability for streaming data need the driver
|
|
|
|
to "register" this capability by calling pci_set_dma_mask() with
|
|
|
|
appropriate parameters. In general this allows more efficient DMA
|
|
|
|
on systems where System RAM exists above 4G _physical_ address.
|
|
|
|
|
|
|
|
Drivers for all PCI-X and PCIe compliant devices must call
|
|
|
|
pci_set_dma_mask() as they are 64-bit DMA devices.
|
|
|
|
|
|
|
|
Similarly, drivers must also "register" this capability if the device
|
|
|
|
can directly address "consistent memory" in System RAM above 4G physical
|
|
|
|
address by calling pci_set_consistent_dma_mask().
|
|
|
|
Again, this includes drivers for all PCI-X and PCIe compliant devices.
|
|
|
|
Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
|
|
|
|
64-bit DMA capable for payload ("streaming") data but not control
|
|
|
|
("consistent") data.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Setup shared control data
|
|
|
|
-------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
|
|
|
|
memory. See Documentation/DMA-API.txt for a full description of
|
|
|
|
the DMA APIs. This section is just a reminder that it needs to be done
|
|
|
|
before enabling DMA on the device.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Initialize device registers
|
|
|
|
---------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Some drivers will need specific "capability" fields programmed
|
|
|
|
or other "vendor specific" register initialized or reset.
|
|
|
|
E.g. clearing pending interrupts.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Register IRQ handler
|
|
|
|
--------------------
|
2007-05-09 14:57:56 +08:00
|
|
|
While calling request_irq() is the last step described here,
|
2006-12-25 16:06:35 +08:00
|
|
|
this is often just another intermediate step to initialize a device.
|
|
|
|
This step can often be deferred until the device is opened for use.
|
|
|
|
|
|
|
|
All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
|
|
|
|
and use the devid to map IRQs to devices (remember that all PCI IRQ lines
|
|
|
|
can be shared).
|
|
|
|
|
|
|
|
request_irq() will associate an interrupt handler and device handle
|
|
|
|
with an interrupt number. Historically interrupt numbers represent
|
|
|
|
IRQ lines which run from the PCI device to the Interrupt controller.
|
|
|
|
With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
|
|
|
|
|
|
|
|
request_irq() also enables the interrupt. Make sure the device is
|
|
|
|
quiesced and does not have any interrupts pending before registering
|
|
|
|
the interrupt handler.
|
|
|
|
|
|
|
|
MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
|
|
|
|
which deliver interrupts to the CPU via a DMA write to a Local APIC.
|
|
|
|
The fundamental difference between MSI and MSI-X is how multiple
|
|
|
|
"vectors" get allocated. MSI requires contiguous blocks of vectors
|
|
|
|
while MSI-X can allocate several individual ones.
|
|
|
|
|
2017-02-15 15:58:22 +08:00
|
|
|
MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
|
|
|
|
PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
|
|
|
|
causes the PCI support to program CPU vector data into the PCI device
|
|
|
|
capability registers. Many architectures, chip-sets, or BIOSes do NOT
|
|
|
|
support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
|
|
|
|
the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
|
|
|
|
specify PCI_IRQ_LEGACY as well.
|
|
|
|
|
|
|
|
Drivers that have different interrupt handlers for MSI/MSI-X and
|
|
|
|
legacy INTx should chose the right one based on the msi_enabled
|
|
|
|
and msix_enabled flags in the pci_dev structure after calling
|
|
|
|
pci_alloc_irq_vectors.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
There are (at least) two really good reasons for using MSI:
|
2019-05-14 22:47:24 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
1) MSI is an exclusive interrupt vector by definition.
|
|
|
|
This means the interrupt handler doesn't have to verify
|
|
|
|
its device caused the interrupt.
|
|
|
|
|
|
|
|
2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
|
|
|
|
to be visible to the host CPU(s) when the MSI is delivered. This
|
|
|
|
is important for both data coherency and avoiding stale control data.
|
|
|
|
This guarantee allows the driver to omit MMIO reads to flush
|
|
|
|
the DMA stream.
|
|
|
|
|
|
|
|
See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
|
|
|
|
of MSI/MSI-X usage.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
PCI device shutdown
|
|
|
|
===================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
When a PCI device driver is being unloaded, most of the following
|
|
|
|
steps need to be performed:
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
- Disable the device from generating IRQs
|
|
|
|
- Release the IRQ (free_irq())
|
|
|
|
- Stop all DMA activity
|
|
|
|
- Release DMA buffers (both streaming and consistent)
|
|
|
|
- Unregister from other subsystems (e.g. scsi or netdev)
|
|
|
|
- Disable device from responding to MMIO/IO Port addresses
|
|
|
|
- Release MMIO/IO Port resource(s)
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Stop IRQs on the device
|
|
|
|
-----------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
How to do this is chip/device specific. If it's not done, it opens
|
|
|
|
the possibility of a "screaming interrupt" if (and only if)
|
|
|
|
the IRQ is shared with another device.
|
|
|
|
|
|
|
|
When the shared IRQ handler is "unhooked", the remaining devices
|
|
|
|
using the same IRQ line will still need the IRQ enabled. Thus if the
|
|
|
|
"unhooked" device asserts IRQ line, the system will respond assuming
|
|
|
|
it was one of the remaining devices asserted the IRQ line. Since none
|
|
|
|
of the other devices will handle the IRQ, the system will "hang" until
|
|
|
|
it decides the IRQ isn't going to get handled and masks the IRQ (100,000
|
|
|
|
iterations later). Once the shared IRQ is masked, the remaining devices
|
|
|
|
will stop functioning properly. Not a nice situation.
|
|
|
|
|
|
|
|
This is another reason to use MSI or MSI-X if it's available.
|
|
|
|
MSI and MSI-X are defined to be exclusive interrupts and thus
|
|
|
|
are not susceptible to the "screaming interrupt" problem.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Release the IRQ
|
|
|
|
---------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Once the device is quiesced (no more IRQs), one can call free_irq().
|
|
|
|
This function will return control once any pending IRQs are handled,
|
|
|
|
"unhook" the drivers IRQ handler from that IRQ, and finally release
|
|
|
|
the IRQ if no one else is using it.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Stop all DMA activity
|
|
|
|
---------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
It's extremely important to stop all DMA operations BEFORE attempting
|
|
|
|
to deallocate DMA control data. Failure to do so can result in memory
|
|
|
|
corruption, hangs, and on some chip-sets a hard crash.
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
Stopping DMA after stopping the IRQs can avoid races where the
|
|
|
|
IRQ handler might restart DMA engines.
|
|
|
|
|
|
|
|
While this step sounds obvious and trivial, several "mature" drivers
|
|
|
|
didn't get this step right in the past.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Release DMA buffers
|
|
|
|
-------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Once DMA is stopped, clean up streaming DMA first.
|
|
|
|
I.e. unmap data buffers and return buffers to "upstream"
|
|
|
|
owners if there is one.
|
|
|
|
|
|
|
|
Then clean up "consistent" buffers which contain the control data.
|
|
|
|
|
|
|
|
See Documentation/DMA-API.txt for details on unmapping interfaces.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Unregister from other subsystems
|
|
|
|
--------------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Most low level PCI device drivers support some other subsystem
|
|
|
|
like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
|
|
|
|
driver isn't losing resources from that other subsystem.
|
|
|
|
If this happens, typically the symptom is an Oops (panic) when
|
|
|
|
the subsystem attempts to call into a driver that has been unloaded.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Disable Device from responding to MMIO/IO Port addresses
|
|
|
|
--------------------------------------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
io_unmap() MMIO or IO Port resources and then call pci_disable_device().
|
|
|
|
This is the symmetric opposite of pci_enable_device().
|
|
|
|
Do not access device registers after calling pci_disable_device().
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Release MMIO/IO Port Resource(s)
|
|
|
|
--------------------------------
|
2006-12-25 16:06:35 +08:00
|
|
|
Call pci_release_region() to mark the MMIO or IO Port range as available.
|
|
|
|
Failure to do so usually results in the inability to reload the driver.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
How to access PCI config space
|
|
|
|
==============================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
|
|
|
|
space of a device represented by `struct pci_dev *`. All these functions return
|
|
|
|
0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
|
|
|
|
text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
|
2005-04-17 06:20:36 +08:00
|
|
|
devices don't fail.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
If you don't have a struct pci_dev available, you can call
|
2019-05-14 22:47:24 +08:00
|
|
|
`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
|
2005-04-17 06:20:36 +08:00
|
|
|
and function on that bus.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
If you access fields in the standard portion of the config header, please
|
2005-04-17 06:20:36 +08:00
|
|
|
use symbolic names of locations and bits declared in <linux/pci.h>.
|
|
|
|
|
2006-12-25 16:06:35 +08:00
|
|
|
If you need to access Extended PCI Capability registers, just call
|
2005-04-17 06:20:36 +08:00
|
|
|
pci_find_capability() for the particular capability and it will find the
|
|
|
|
corresponding register block for you.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Other interesting functions
|
|
|
|
===========================
|
2005-04-17 06:20:36 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
============================= ================================================
|
2013-09-02 14:34:40 +08:00
|
|
|
pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
|
|
|
|
bus and slot and number. If the device is
|
|
|
|
found, its reference count is increased.
|
2005-04-17 06:20:36 +08:00
|
|
|
pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
|
|
|
|
pci_find_capability() Find specified capability in device's capability
|
|
|
|
list.
|
|
|
|
pci_resource_start() Returns bus start address for a given PCI region
|
|
|
|
pci_resource_end() Returns bus end address for a given PCI region
|
|
|
|
pci_resource_len() Returns the byte length of a PCI region
|
|
|
|
pci_set_drvdata() Set private driver data pointer for a pci_dev
|
|
|
|
pci_get_drvdata() Return private driver data pointer for a pci_dev
|
|
|
|
pci_set_mwi() Enable Memory-Write-Invalidate transactions.
|
|
|
|
pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
|
2019-05-14 22:47:24 +08:00
|
|
|
============================= ================================================
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Miscellaneous hints
|
|
|
|
===================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
When displaying PCI device names to the user (for example when a driver wants
|
|
|
|
to tell the user what card has it found), please use pci_name(pci_dev).
|
2005-04-17 06:20:36 +08:00
|
|
|
|
|
|
|
Always refer to the PCI devices by a pointer to the pci_dev structure.
|
|
|
|
All PCI layer functions use this identification and it's the only
|
|
|
|
reasonable one. Don't use bus/slot/function numbers except for very
|
|
|
|
special purposes -- on systems with multiple primary buses their semantics
|
|
|
|
can be pretty complex.
|
|
|
|
|
|
|
|
Don't try to turn on Fast Back to Back writes in your driver. All devices
|
|
|
|
on the bus need to be capable of doing it, so this is something which needs
|
|
|
|
to be handled by platform and generic code, not individual drivers.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Vendor and device identifications
|
|
|
|
=================================
|
2006-04-18 17:20:55 +08:00
|
|
|
|
2015-03-30 16:32:34 +08:00
|
|
|
Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
|
|
|
|
are shared across multiple drivers. You can add private definitions in
|
|
|
|
your driver if they're helpful, or just use plain hex constants.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2015-03-30 16:32:34 +08:00
|
|
|
The device IDs are arbitrary hex numbers (vendor controlled) and normally used
|
|
|
|
only in a single location, the pci_device_id table.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2018-02-23 05:00:43 +08:00
|
|
|
Please DO submit new vendor/device IDs to http://pci-ids.ucw.cz/.
|
|
|
|
There are mirrors of the pci.ids file at http://pciids.sourceforge.net/
|
|
|
|
and https://github.com/pciutils/pciids.
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2006-04-18 17:20:55 +08:00
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
Obsolete functions
|
|
|
|
==================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
2005-04-17 06:20:36 +08:00
|
|
|
There are several functions which you might come across when trying to
|
|
|
|
port an old driver to the new PCI interface. They are no longer present
|
|
|
|
in the kernel as they aren't compatible with hotplug or PCI domains or
|
|
|
|
having sane locking.
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
================= ===========================================
|
2006-12-25 16:06:35 +08:00
|
|
|
pci_find_device() Superseded by pci_get_device()
|
|
|
|
pci_find_subsys() Superseded by pci_get_subsys()
|
2013-09-02 14:34:40 +08:00
|
|
|
pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
|
|
|
|
pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
|
2019-05-14 22:47:24 +08:00
|
|
|
================= ===========================================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
The alternative is the traditional PCI device driver that walks PCI
|
|
|
|
device lists. This is still possible but discouraged.
|
|
|
|
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
MMIO Space and "Write Posting"
|
|
|
|
==============================
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
Converting a driver from using I/O Port space to using MMIO space
|
|
|
|
often requires some additional changes. Specifically, "write posting"
|
|
|
|
needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
|
|
|
|
already do this. I/O Port space guarantees write transactions reach the PCI
|
|
|
|
device before the CPU can continue. Writes to MMIO space allow the CPU
|
|
|
|
to continue before the transaction reaches the PCI device. HW weenies
|
|
|
|
call this "Write Posting" because the write completion is "posted" to
|
|
|
|
the CPU before the transaction has reached its destination.
|
|
|
|
|
|
|
|
Thus, timing sensitive code should add readl() where the CPU is
|
|
|
|
expected to wait before doing other work. The classic "bit banging"
|
2019-05-14 22:47:24 +08:00
|
|
|
sequence works fine for I/O Port space::
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
for (i = 8; --i; val >>= 1) {
|
|
|
|
outb(val & 1, ioport_reg); /* write bit */
|
|
|
|
udelay(10);
|
|
|
|
}
|
|
|
|
|
2019-05-14 22:47:24 +08:00
|
|
|
The same sequence for MMIO space should be::
|
2006-12-25 16:06:35 +08:00
|
|
|
|
|
|
|
for (i = 8; --i; val >>= 1) {
|
|
|
|
writeb(val & 1, mmio_reg); /* write bit */
|
|
|
|
readb(safe_mmio_reg); /* flush posted write */
|
|
|
|
udelay(10);
|
|
|
|
}
|
|
|
|
|
|
|
|
It is important that "safe_mmio_reg" not have any side effects that
|
|
|
|
interferes with the correct operation of the device.
|
|
|
|
|
|
|
|
Another case to watch out for is when resetting a PCI device. Use PCI
|
|
|
|
Configuration space reads to flush the writel(). This will gracefully
|
|
|
|
handle the PCI master abort on all platforms if the PCI device is
|
|
|
|
expected to not respond to a readl(). Most x86 platforms will allow
|
|
|
|
MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
|
|
|
|
(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
|