^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) How To Write Linux PCI Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) :Authors: - Martin Mares <mj@ucw.cz>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) - Grant Grundler <grundler@parisc-linux.org>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) The world of PCI is vast and full of (mostly unpleasant) surprises.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Since each CPU architecture implements different chip-sets and PCI devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) have different requirements (erm, "features"), the result is the PCI support
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) in the Linux kernel is not as trivial as one would wish. This short paper
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) tries to introduce all potential driver authors to Linux APIs for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) PCI device drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) A more complete resource is the third edition of "Linux Device Drivers"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) LDD3 is available for free (under Creative Commons License) from:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) https://lwn.net/Kernel/LDD3/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) However, keep in mind that all documents are subject to "bit rot".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Refer to the source code if things are not working as described here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) Please send questions/comments/patches about Linux PCI API to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Structure of PCI drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) ========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) PCI drivers "discover" PCI devices in a system via pci_register_driver().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) Actually, it's the other way around. When the PCI generic code discovers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) a new device, the driver with a matching "description" will be notified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) Details on this below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) pci_register_driver() leaves most of the probing for devices to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) the PCI layer and supports online insertion/removal of devices [thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver].
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) pci_register_driver() call requires passing in a table of function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) pointers and thus dictates the high level structure of a driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Once the driver knows about a PCI device and takes ownership, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) driver generally needs to perform the following initialization:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) - Enable the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) - Request MMIO/IOP resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) - Set the DMA mask size (for both coherent and streaming DMA)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - Allocate and initialize shared control data (pci_allocate_coherent())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - Access device configuration space (if needed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) - Register IRQ handler (request_irq())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - Enable DMA/processing engines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) When done using the device, and perhaps the module needs to be unloaded,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) the driver needs to take the follow steps:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) - Disable the device from generating IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) - Release the IRQ (free_irq())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) - Stop all DMA activity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) - Release DMA buffers (both streaming and coherent)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) - Unregister from other subsystems (e.g. scsi or netdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) - Release MMIO/IOP resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) - Disable the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) Most of these topics are covered in the following sections.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) For the rest look at LDD3 or <linux/pci.h> .
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the PCI functions described below are defined as inline functions either
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) completely empty or just returning an appropriate error codes to avoid
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) lots of ifdefs in the drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) pci_register_driver() call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) PCI device drivers call ``pci_register_driver()`` during their
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) initialization with a pointer to a structure describing the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) (``struct pci_driver``):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) .. kernel-doc:: include/linux/pci.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) :functions: pci_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) The ID table is an array of ``struct pci_device_id`` entries ending with an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) all-zero entry. Definitions with static const are generally preferred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) .. kernel-doc:: include/linux/mod_devicetable.h
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) :functions: pci_device_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) a pci_device_id table.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) New PCI IDs may be added to a device driver pci_ids table at runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) as shown below::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) echo "vendor device subvendor subdevice class class_mask driver_data" > \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) /sys/bus/pci/drivers/{driver}/new_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) All fields are passed in as hexadecimal values (no leading 0x).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) The vendor and device fields are mandatory, the others are optional. Users
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) need pass only as many optional fields as necessary:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) - class and classmask fields default to 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) - driver_data defaults to 0UL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Note that driver_data must match the value used by any of the pci_device_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) entries defined in the driver. This makes the driver_data field mandatory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) if all the pci_device_id entries have a non-zero driver_data value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Once added, the driver probe routine will be invoked for any unclaimed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) PCI devices listed in its (newly updated) pci_ids list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) When the driver exits, it just calls pci_unregister_driver() and the PCI layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) automatically calls the remove hook for all devices handled by the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) "Attributes" for driver functions/data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Please mark the initialization and cleanup functions where appropriate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) (the corresponding macros are defined in <linux/init.h>):
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) ====== =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) __init Initialization code. Thrown away after the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) initializes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) __exit Exit code. Ignored for non-modular drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) ====== =================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Tips on when/where to use the above attributes:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) - The module_init()/module_exit() functions (and all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) initialization functions called _only_ from these)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) should be marked __init/__exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) - Do not mark the struct pci_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) - Do NOT mark a function if you are not sure which mark to use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) Better to not mark the function than mark the function wrong.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) How to find PCI devices manually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) ================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) PCI drivers should have a really good reason for not using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) pci_register_driver() interface to search for PCI devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) The main reason PCI devices are controlled by multiple drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) is because one PCI device implements several different HW services.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) E.g. combined serial/parallel port/floppy controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) A manual search may be performed using the following constructs:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) Searching by vendor and device ID::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) struct pci_dev *dev = NULL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) configure_device(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) Searching by class ID (iterate in a similar way)::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) pci_get_class(CLASS_ID, dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Searching by both vendor/device and subsystem vendor/device ID::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) You can use the constant PCI_ANY_ID as a wildcard replacement for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) VENDOR_ID or DEVICE_ID. This allows searching for any device from a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) specific vendor, for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) These functions are hotplug-safe. They increment the reference count on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) the pci_dev that they return. You must eventually (possibly at module unload)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) decrement the reference count on these devices by calling pci_dev_put().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) Device Initialization Steps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) As noted in the introduction, most PCI drivers need the following steps
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) for device initialization:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) - Enable the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) - Request MMIO/IOP resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) - Set the DMA mask size (for both coherent and streaming DMA)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) - Allocate and initialize shared control data (pci_allocate_coherent())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) - Access device configuration space (if needed)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) - Register IRQ handler (request_irq())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) - Enable DMA/processing engines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) The driver can access PCI config space registers at any time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) (Well, almost. When running BIST, config space can go away...but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) that will just result in a PCI Bus Master Abort and config reads
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) will return garbage).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) Enable the PCI device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) Before touching any device registers, the driver needs to enable
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) the PCI device by calling pci_enable_device(). This will:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) - wake up the device if it was in suspended state,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) - allocate I/O and memory regions of the device (if BIOS did not),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) - allocate an IRQ (if BIOS did not).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) pci_enable_device() can fail! Check the return value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) .. warning::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) OS BUG: we don't check resource allocations before enabling those
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) resources. The sequence would make more sense if we called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) pci_request_resources() before calling pci_enable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) Currently, the device drivers can't detect the bug when two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) devices have been allocated the same range. This is not a common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) problem and unlikely to get fixed soon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) This has been discussed before but not changed as of 2.6.19:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) https://lore.kernel.org/r/20060302180025.GC28895@flint.arm.linux.org.uk/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) pci_set_master() will enable DMA by setting the bus master bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) in the PCI_COMMAND register. It also fixes the latency timer value if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) it's set to something bogus by the BIOS. pci_clear_master() will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) disable DMA by clearing the bus master bit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) If the PCI device can use the PCI Memory-Write-Invalidate transaction,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) and also ensures that the cache line size register is set correctly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) Check the return value of pci_set_mwi() as not all architectures
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) or chip-sets may support Memory-Write-Invalidate. Alternatively,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) if Mem-Wr-Inval would be nice to have but is not required, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) pci_try_set_mwi() to have the system do its best effort at enabling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Mem-Wr-Inval.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) Request MMIO/IOP resources
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) Memory (MMIO), and I/O port addresses should NOT be read directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) from the PCI device config space. Use the values in the pci_dev structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) as the PCI "bus address" might have been remapped to a "host physical"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) address by the arch/chip-set specific kernel support.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) See Documentation/driver-api/io-mapping.rst for how to access device registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) or device memory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) The device driver needs to call pci_request_region() to verify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) no other device is already using the same address resource.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) Conversely, drivers should call pci_release_region() AFTER
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) calling pci_disable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) The idea is to prevent two devices colliding on the same address range.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) .. tip::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) See OS BUG comment above. Currently (2.6.19), The driver can only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) determine MMIO and IO Port resource availability _after_ calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) pci_enable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) Generic flavors of pci_request_region() are request_mem_region()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) (for MMIO ranges) and request_region() (for IO Port ranges).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) Use these for address resources that are not described by "normal" PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) BARs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) Also see pci_request_selected_regions() below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) Set the DMA mask size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) .. note::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) If anything below doesn't make sense, please refer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) :doc:`/core-api/dma-api`. This section is just a reminder that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) drivers need to indicate DMA capabilities of the device and is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) an authoritative source for DMA interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) While all drivers should explicitly indicate the DMA capability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) (e.g. 32 or 64 bit) of the PCI bus master, devices with more than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) 32-bit bus master capability for streaming data need the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) to "register" this capability by calling pci_set_dma_mask() with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) appropriate parameters. In general this allows more efficient DMA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) on systems where System RAM exists above 4G _physical_ address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) Drivers for all PCI-X and PCIe compliant devices must call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) pci_set_dma_mask() as they are 64-bit DMA devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) Similarly, drivers must also "register" this capability if the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) can directly address "consistent memory" in System RAM above 4G physical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) address by calling pci_set_consistent_dma_mask().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) Again, this includes drivers for all PCI-X and PCIe compliant devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) 64-bit DMA capable for payload ("streaming") data but not control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) ("consistent") data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) Setup shared control data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) memory. See :doc:`/core-api/dma-api` for a full description of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) the DMA APIs. This section is just a reminder that it needs to be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) before enabling DMA on the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Initialize device registers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) Some drivers will need specific "capability" fields programmed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) or other "vendor specific" register initialized or reset.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) E.g. clearing pending interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) Register IRQ handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) While calling request_irq() is the last step described here,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) this is often just another intermediate step to initialize a device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) This step can often be deferred until the device is opened for use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) All interrupt handlers for IRQ lines should be registered with IRQF_SHARED
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) and use the devid to map IRQs to devices (remember that all PCI IRQ lines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) can be shared).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) request_irq() will associate an interrupt handler and device handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) with an interrupt number. Historically interrupt numbers represent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) IRQ lines which run from the PCI device to the Interrupt controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) With MSI and MSI-X (more below) the interrupt number is a CPU "vector".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) request_irq() also enables the interrupt. Make sure the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) quiesced and does not have any interrupts pending before registering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) the interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) which deliver interrupts to the CPU via a DMA write to a Local APIC.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) The fundamental difference between MSI and MSI-X is how multiple
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) "vectors" get allocated. MSI requires contiguous blocks of vectors
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) while MSI-X can allocate several individual ones.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) MSI capability can be enabled by calling pci_alloc_irq_vectors() with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) causes the PCI support to program CPU vector data into the PCI device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) capability registers. Many architectures, chip-sets, or BIOSes do NOT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) support MSI or MSI-X and a call to pci_alloc_irq_vectors with just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) specify PCI_IRQ_LEGACY as well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) Drivers that have different interrupt handlers for MSI/MSI-X and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) legacy INTx should chose the right one based on the msi_enabled
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) and msix_enabled flags in the pci_dev structure after calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) pci_alloc_irq_vectors.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) There are (at least) two really good reasons for using MSI:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) 1) MSI is an exclusive interrupt vector by definition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) This means the interrupt handler doesn't have to verify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) its device caused the interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) to be visible to the host CPU(s) when the MSI is delivered. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) is important for both data coherency and avoiding stale control data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353) This guarantee allows the driver to omit MMIO reads to flush
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) the DMA stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) of MSI/MSI-X usage.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) PCI device shutdown
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) When a PCI device driver is being unloaded, most of the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) steps need to be performed:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) - Disable the device from generating IRQs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) - Release the IRQ (free_irq())
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) - Stop all DMA activity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369) - Release DMA buffers (both streaming and consistent)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) - Unregister from other subsystems (e.g. scsi or netdev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) - Disable device from responding to MMIO/IO Port addresses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) - Release MMIO/IO Port resource(s)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) Stop IRQs on the device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) How to do this is chip/device specific. If it's not done, it opens
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) the possibility of a "screaming interrupt" if (and only if)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379) the IRQ is shared with another device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) When the shared IRQ handler is "unhooked", the remaining devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) using the same IRQ line will still need the IRQ enabled. Thus if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) "unhooked" device asserts IRQ line, the system will respond assuming
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) it was one of the remaining devices asserted the IRQ line. Since none
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) of the other devices will handle the IRQ, the system will "hang" until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) it decides the IRQ isn't going to get handled and masks the IRQ (100,000
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) iterations later). Once the shared IRQ is masked, the remaining devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) will stop functioning properly. Not a nice situation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) This is another reason to use MSI or MSI-X if it's available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) MSI and MSI-X are defined to be exclusive interrupts and thus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) are not susceptible to the "screaming interrupt" problem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) Release the IRQ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) Once the device is quiesced (no more IRQs), one can call free_irq().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) This function will return control once any pending IRQs are handled,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) "unhook" the drivers IRQ handler from that IRQ, and finally release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) the IRQ if no one else is using it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) Stop all DMA activity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) It's extremely important to stop all DMA operations BEFORE attempting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) to deallocate DMA control data. Failure to do so can result in memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) corruption, hangs, and on some chip-sets a hard crash.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) Stopping DMA after stopping the IRQs can avoid races where the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) IRQ handler might restart DMA engines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) While this step sounds obvious and trivial, several "mature" drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) didn't get this step right in the past.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) Release DMA buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) Once DMA is stopped, clean up streaming DMA first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) I.e. unmap data buffers and return buffers to "upstream"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) owners if there is one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) Then clean up "consistent" buffers which contain the control data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) See :doc:`/core-api/dma-api` for details on unmapping interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427) Unregister from other subsystems
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) Most low level PCI device drivers support some other subsystem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430) like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431) driver isn't losing resources from that other subsystem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) If this happens, typically the symptom is an Oops (panic) when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) the subsystem attempts to call into a driver that has been unloaded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436) Disable Device from responding to MMIO/IO Port addresses
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) --------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) io_unmap() MMIO or IO Port resources and then call pci_disable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) This is the symmetric opposite of pci_enable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) Do not access device registers after calling pci_disable_device().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) Release MMIO/IO Port Resource(s)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) Call pci_release_region() to mark the MMIO or IO Port range as available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446) Failure to do so usually results in the inability to reload the driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449) How to access PCI config space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452) You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) space of a device represented by `struct pci_dev *`. All these functions return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) 0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) devices don't fail.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458) If you don't have a struct pci_dev available, you can call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) and function on that bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) If you access fields in the standard portion of the config header, please
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463) use symbolic names of locations and bits declared in <linux/pci.h>.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) If you need to access Extended PCI Capability registers, just call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) pci_find_capability() for the particular capability and it will find the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467) corresponding register block for you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470) Other interesting functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) ===========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473) ============================= ================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475) bus and slot and number. If the device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) found, its reference count is increased.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) pci_find_capability() Find specified capability in device's capability
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479) list.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) pci_resource_start() Returns bus start address for a given PCI region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) pci_resource_end() Returns bus end address for a given PCI region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482) pci_resource_len() Returns the byte length of a PCI region
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) pci_set_drvdata() Set private driver data pointer for a pci_dev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) pci_get_drvdata() Return private driver data pointer for a pci_dev
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485) pci_set_mwi() Enable Memory-Write-Invalidate transactions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) ============================= ================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) Miscellaneous hints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493) When displaying PCI device names to the user (for example when a driver wants
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) to tell the user what card has it found), please use pci_name(pci_dev).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) Always refer to the PCI devices by a pointer to the pci_dev structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) All PCI layer functions use this identification and it's the only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498) reasonable one. Don't use bus/slot/function numbers except for very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499) special purposes -- on systems with multiple primary buses their semantics
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) can be pretty complex.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502) Don't try to turn on Fast Back to Back writes in your driver. All devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) on the bus need to be capable of doing it, so this is something which needs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) to be handled by platform and generic code, not individual drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) Vendor and device identifications
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508) =================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510) Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) are shared across multiple drivers. You can add private definitions in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) your driver if they're helpful, or just use plain hex constants.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) The device IDs are arbitrary hex numbers (vendor controlled) and normally used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) only in a single location, the pci_device_id table.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) There's a mirror of the pci.ids file at https://github.com/pciutils/pciids.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) Obsolete functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) There are several functions which you might come across when trying to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525) port an old driver to the new PCI interface. They are no longer present
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) in the kernel as they aren't compatible with hotplug or PCI domains or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) having sane locking.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529) ================= ===========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) pci_find_device() Superseded by pci_get_device()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) pci_find_subsys() Superseded by pci_get_subsys()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532) pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) ================= ===========================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) The alternative is the traditional PCI device driver that walks PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537) device lists. This is still possible but discouraged.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) MMIO Space and "Write Posting"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) ==============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) Converting a driver from using I/O Port space to using MMIO space
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) often requires some additional changes. Specifically, "write posting"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545) needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) already do this. I/O Port space guarantees write transactions reach the PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) device before the CPU can continue. Writes to MMIO space allow the CPU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548) to continue before the transaction reaches the PCI device. HW weenies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) call this "Write Posting" because the write completion is "posted" to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550) the CPU before the transaction has reached its destination.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) Thus, timing sensitive code should add readl() where the CPU is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) expected to wait before doing other work. The classic "bit banging"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554) sequence works fine for I/O Port space::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) for (i = 8; --i; val >>= 1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) outb(val & 1, ioport_reg); /* write bit */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) udelay(10);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) The same sequence for MMIO space should be::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) for (i = 8; --i; val >>= 1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) writeb(val & 1, mmio_reg); /* write bit */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565) readb(safe_mmio_reg); /* flush posted write */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) udelay(10);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) It is important that "safe_mmio_reg" not have any side effects that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) interferes with the correct operation of the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) Another case to watch out for is when resetting a PCI device. Use PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) Configuration space reads to flush the writel(). This will gracefully
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574) handle the PCI master abort on all platforms if the PCI device is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) expected to not respond to a readl(). Most x86 platforms will allow
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577) (e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags