Documentation/pci.txt

   1                          How To Write Linux PCI Drivers
   2
   3                   by Martin Mares <mj@suse.cz> on 07-Feb-2000
   4
   5 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   6 The world of PCI is vast and it's full of (mostly unpleasant) surprises.
   7 Different PCI devices have different requirements and different bugs --
   8 because of this, the PCI support layer in Linux kernel is not as trivial
   9 as one would wish. This short pamphlet tries to help all potential driver
  10 authors to find their way through the deep forests of PCI handling.
  11
  12
  13 0. Structure of PCI drivers
  14 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 There exist two kinds of PCI drivers: new-style ones (which leave most of
  16 probing for devices to the PCI layer and support online insertion and removal
  17 of devices [thus supporting PCI, hot-pluggable PCI and CardBus in single
  18 driver]) and old-style ones which just do all the probing themselves. Unless
  19 you have a very good reason to do so, please don't use the old way of probing
  20 in any new code. After the driver finds the devices it wishes to operate
  21 on (either the old or the new way), it needs to perform the following steps:
  22
  23         Enable the device
  24         Access device configuration space
  25         Discover resources (addresses and IRQ numbers) provided by the device
  26         Allocate these resources
  27         Communicate with the device
  28
  29 Most of these topics are covered by the following sections, for the rest
  30 look at <linux/pci.h>, it's hopefully well commented.
  31
  32 If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
  33 the functions described below are defined as inline functions either completely
  34 empty or just returning an appropriate error codes to avoid lots of ifdefs
  35 in the drivers.
  36
  37
  38 1. New-style drivers
  39 ~~~~~~~~~~~~~~~~~~~~
  40 The new-style drivers just call pci_register_driver during their initialization
  41 with a pointer to a structure describing the driver (struct pci_driver) which
  42 contains:
  43
  44         name            Name of the driver
  45         id_table        Pointer to table of device ID's the driver is
  46                         interested in
  47         probe           Pointer to a probing function which gets called (during
  48                         execution of pci_register_driver for already existing
  49                         devices or later if a new device gets inserted) for all
  50                         PCI devices which match the ID table and are not handled
  51                         by the other drivers yet. This function gets passed a pointer
  52                         to the pci_dev structure representing the device and also
  53                         which entry in the ID table did the device match. It returns
  54                         zero when the driver has accepted the device or an error
  55                         code (negative number) otherwise. This function always gets
  56                         called from process context, so it can sleep.
  57         remove          Pointer to a function which gets called whenever a device
  58                         being handled by this driver is removed (either during
  59                         deregistration of the driver or when it's manually pulled
  60                         out of a hot-pluggable slot). This function can be called
  61                         from interrupt context.
  62         suspend,        Power management hooks (currently used only for CardBus
  63         resume          cards) -- called when the device goes to sleep or is
  64                         resumed.
  65
  66 The ID table is an array of struct pci_device_id ending with a all-zero entry.
  67 Each entry consists of:
  68
  69         vendor, device  Vendor and device ID to match (or PCI_ANY_ID)
  70         subvendor,      Subsystem vendor and device ID to match (or PCI_ANY_ID)
  71         subdevice
  72         class,          Device class to match. The class_mask tells which bits
  73         class_mask      of the class are honored during the comparison.
  74         driver_data     Data private to the driver.
  75
  76 When the driver exits, it just calls pci_deregister_driver() and the PCI layer
  77 automatically calls the remove hook for all devices handled by the driver.
  78
  79 Please mark the initialization and cleanup functions where appropriate
  80 (the corresponding macros are defined in <linux/init.h>):
  81
  82         __init          Initialization code. Thrown away after the driver
  83                         initializes.
  84         __exit          Exit code. Ignored for non-modular drivers.
  85         __devinit       Device initialization code. Identical to __init if
  86                         the kernel is not compiled with CONFIG_HOTPLUG, normal
  87                         function otherwise.
  88         __devexit       The same for __exit.
  89
  90
  91 2. How to find PCI devices manually (the old style)
  92 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  93 PCI drivers not using the pci_register_driver() interface search
  94 for PCI devices manually using the following constructs:
  95
  96 Searching by vendor and device ID:
  97
  98         struct pci_dev *dev = NULL;
  99         while (dev = pci_find_device(VENDOR_ID, DEVICE_ID, dev))
 100                 configure_device(dev);
 101
 102 Searching by class ID (iterate in a similar way):
 103
 104         pci_find_class(CLASS_ID, dev)
 105
 106 Searching by both vendor/device and subsystem vendor/device ID:
 107
 108         pci_find_subsys(VENDOR_ID, DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
 109
 110    You can use the constant PCI_ANY_ID as a wildcard replacement for
 111 VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
 112 specific vendor, for example.
 113
 114    In case you need to decide according to some more complex criteria,
 115 you can walk the list of all known PCI devices yourself:
 116
 117         struct pci_dev *dev;
 118         pci_for_each_dev(dev) {
 119                 ... do anything you want with dev ...
 120         }
 121
 122 For compatibility with device ordering in older kernels, you can also
 123 use pci_for_each_dev_reverse(dev) for walking the list in the opposite
 124 direction.
 125
 126
 127 3. Enabling devices
 128 ~~~~~~~~~~~~~~~~~~~
 129    Before you do anything with the device you've found, you need to enable
 130 it by calling pci_enable_device() which enables I/O and memory regions of
 131 the device, assigns missing resources if needed and wakes up the device
 132 if it was in suspended state. Please note that this function can fail.
 133
 134    If you want to use the device in bus mastering mode, call pci_set_master()
 135 which enables the bus master bit in PCI_COMMAND register and also fixes
 136 the latency timer value if it's set to something bogus by the BIOS.
 137
 138
 139 4. How to access PCI config space
 140 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 141    You can use pci_(read|write)_config_(byte|word|dword) to access the config
 142 space of a device represented by struct pci_dev *. All these functions return 0
 143 when successful or an error code (PCIBIOS_...) which can be translated to a text
 144 string by pcibios_strerror. Most drivers expect that accesses to valid PCI
 145 devices don't fail.
 146
 147    If you access fields in the standard portion of the config header, please
 148 use symbolic names of locations and bits declared in <linux/pci.h>.
 149
 150    If you need to access Extended PCI Capability registers, just call
 151 pci_find_capability() for the particular capability and it will find the
 152 corresponding register block for you.
 153
 154
 155 5. Addresses and interrupts
 156 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 157    Memory and port addresses and interrupt numbers should NOT be read from the
 158 config space. You should use the values in the pci_dev structure as they might
 159 have been remapped by the kernel.
 160
 161    See Documentation/IO-mapping.txt for how to access device memory.
 162
 163    You still need to call request_region() for I/O regions and request_mem_region()
 164 for memory regions to make sure nobody else is using the same device.
 165
 166    All interrupt handlers should be registered with SA_SHIRQ and use the devid
 167 to map IRQs to devices (remember that all PCI interrupts are shared).
 168
 169
 170 6. Other interesting functions
 171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 172 pci_find_slot()                 Find pci_dev corresponding to given bus and
 173                                 slot numbers.
 174 pci_set_power_state()           Set PCI Power Management state (0=D0 ... 3=D3)
 175 pci_find_capability()           Find specified capability in device's capability
 176                                 list.
 177
 178
 179 7. Miscellaneous hints
 180 ~~~~~~~~~~~~~~~~~~~~~~
 181 When displaying PCI slot names to the user (for example when a driver wants
 182 to tell the user what card has it found), please use pci_dev->slot_name
 183 for this purpose.
 184
 185 Always refer to the PCI devices by a pointer to the pci_dev structure.
 186 All PCI layer functions use this identification and it's the only
 187 reasonable one. Don't use bus/slot/function numbers except for very
 188 special purposes -- on systems with multiple primary buses their semantics
 189 can be pretty complex.
 190
 191 If you're going to use PCI bus mastering DMA, take a look at
 192 Documentation/DMA-mapping.txt.
 193
 194
 195 8. Obsolete functions
 196 ~~~~~~~~~~~~~~~~~~~~~
 197 There are several functions kept only for compatibility with old drivers
 198 not updated to the new PCI interface. Please don't use them in new code.
 199
 200 pcibios_present()               Since ages, you don't need to test presence
 201                                 of PCI subsystem when trying to talk with it.
 202                                 If it's not there, the list of PCI devices
 203                                 is empty and all functions for searching for
 204                                 devices just return NULL.
 205 pcibios_(read|write)_*          Superseded by their pci_(read|write)_*
 206                                 counterparts.
 207 pcibios_find_*                  Superseded by their pci_find_* counterparts.