Documentation/pci.txt

   1                          How To Write Linux PCI Drivers
   2
   3                    by Martin Mares <mj@ucw.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.  Most drivers should export this
  47                         table using MODULE_DEVICE_TABLE(pci,...).
  48                         Set to NULL to call probe() function for every
  49                         PCI device known to the system.
  50         probe           Pointer to a probing function which gets called (during
  51                         execution of pci_register_driver for already existing
  52                         devices or later if a new device gets inserted) for all
  53                         PCI devices which match the ID table and are not handled
  54                         by the other drivers yet. This function gets passed a
  55                         pointer to the pci_dev structure representing the device
  56                         and also which entry in the ID table did the device
  57                         match. It returns zero when the driver has accepted the
  58                         device or an error code (negative number) otherwise.
  59                         This function always gets called from process context,
  60                         so it can sleep.
  61         remove          Pointer to a function which gets called whenever a
  62                         device being handled by this driver is removed (either
  63                         during deregistration of the driver or when it's
  64                         manually pulled out of a hot-pluggable slot). This
  65                         function always gets called from process context, so it
  66                         can sleep.
  67         save_state      Save a device's state before it's suspend.
  68         suspend         Put device into low power state.
  69         resume          Wake device from low power state.
  70         enable_wake     Enable device to generate wake events from a low power
  71                         state.
  72
  73                         (Please see Documentation/power/pci.txt for descriptions
  74                         of PCI Power Management and the related functions)
  75
  76 The ID table is an array of struct pci_device_id ending with a all-zero entry.
  77 Each entry consists of:
  78
  79         vendor, device  Vendor and device ID to match (or PCI_ANY_ID)
  80         subvendor,      Subsystem vendor and device ID to match (or PCI_ANY_ID)
  81         subdevice
  82         class,          Device class to match. The class_mask tells which bits
  83         class_mask      of the class are honored during the comparison.
  84         driver_data     Data private to the driver.
  85
  86 When the driver exits, it just calls pci_unregister_driver() and the PCI layer
  87 automatically calls the remove hook for all devices handled by the driver.
  88
  89 Please mark the initialization and cleanup functions where appropriate
  90 (the corresponding macros are defined in <linux/init.h>):
  91
  92         __init          Initialization code. Thrown away after the driver
  93                         initializes.
  94         __exit          Exit code. Ignored for non-modular drivers.
  95         __devinit       Device initialization code. Identical to __init if
  96                         the kernel is not compiled with CONFIG_HOTPLUG, normal
  97                         function otherwise.
  98         __devexit       The same for __exit.
  99
 100 Tips:
 101         The module_init()/module_exit() functions (and all initialization
 102         functions called only from these) should be marked __init/exit.
 103         The struct pci_driver shouldn't be marked with any of these tags.
 104         The ID table array should be marked __devinitdata.
 105         The probe() and remove() functions (and all initialization
 106         functions called only from these) should be marked __devinit/exit.
 107         If you are sure the driver is not a hotplug driver then use only
 108         __init/exit __initdata/exitdata.
 109
 110         Pointers to functions marked as __devexit must be created using
 111         __devexit_p(function_name).  That will generate the function
 112         name or NULL if the __devexit function will be discarded.
 113
 114
 115 2. How to find PCI devices manually (the old style)
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117 PCI drivers not using the pci_register_driver() interface search
 118 for PCI devices manually using the following constructs:
 119
 120 Searching by vendor and device ID:
 121
 122         struct pci_dev *dev = NULL;
 123         while (dev = pci_find_device(VENDOR_ID, DEVICE_ID, dev))
 124                 configure_device(dev);
 125
 126 Searching by class ID (iterate in a similar way):
 127
 128         pci_find_class(CLASS_ID, dev)
 129
 130 Searching by both vendor/device and subsystem vendor/device ID:
 131
 132         pci_find_subsys(VENDOR_ID, DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
 133
 134    You can use the constant PCI_ANY_ID as a wildcard replacement for
 135 VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
 136 specific vendor, for example.
 137
 138    In case you need to decide according to some more complex criteria,
 139 you can walk the list of all known PCI devices yourself:
 140
 141         struct pci_dev *dev;
 142         pci_for_each_dev(dev) {
 143                 ... do anything you want with dev ...
 144         }
 145
 146 For compatibility with device ordering in older kernels, you can also
 147 use pci_for_each_dev_reverse(dev) for walking the list in the opposite
 148 direction.
 149
 150
 151 3. Enabling devices
 152 ~~~~~~~~~~~~~~~~~~~
 153    Before you do anything with the device you've found, you need to enable
 154 it by calling pci_enable_device() which enables I/O and memory regions of
 155 the device, assigns missing resources if needed and wakes up the device
 156 if it was in suspended state. Please note that this function can fail.
 157
 158    If you want to use the device in bus mastering mode, call pci_set_master()
 159 which enables the bus master bit in PCI_COMMAND register and also fixes
 160 the latency timer value if it's set to something bogus by the BIOS.
 161
 162    If you want to use the PCI Memory-Write-Invalidate transaction,
 163 call pci_set_mwi().  This enables bit PCI_COMMAND bit for Mem-Wr-Inval
 164 and also ensures that the cache line size register is set correctly.
 165 Make sure to check the return value of pci_set_mwi(), not all architectures
 166 may support Memory-Write-Invalidate.
 167
 168 4. How to access PCI config space
 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 170    You can use pci_(read|write)_config_(byte|word|dword) to access the config
 171 space of a device represented by struct pci_dev *. All these functions return 0
 172 when successful or an error code (PCIBIOS_...) which can be translated to a text
 173 string by pcibios_strerror. Most drivers expect that accesses to valid PCI
 174 devices don't fail.
 175
 176    If you access fields in the standard portion of the config header, please
 177 use symbolic names of locations and bits declared in <linux/pci.h>.
 178
 179    If you need to access Extended PCI Capability registers, just call
 180 pci_find_capability() for the particular capability and it will find the
 181 corresponding register block for you.
 182
 183
 184 5. Addresses and interrupts
 185 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 186    Memory and port addresses and interrupt numbers should NOT be read from the
 187 config space. You should use the values in the pci_dev structure as they might
 188 have been remapped by the kernel.
 189
 190    See Documentation/IO-mapping.txt for how to access device memory.
 191
 192    You still need to call request_region() for I/O regions and
 193 request_mem_region() for memory regions to make sure nobody else is using the
 194 same device.
 195
 196    All interrupt handlers should be registered with SA_SHIRQ and use the devid
 197 to map IRQs to devices (remember that all PCI interrupts are shared).
 198
 199
 200 6. Other interesting functions
 201 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 202 pci_find_slot()                 Find pci_dev corresponding to given bus and
 203                                 slot numbers.
 204 pci_set_power_state()           Set PCI Power Management state (0=D0 ... 3=D3)
 205 pci_find_capability()           Find specified capability in device's capability
 206                                 list.
 207 pci_module_init()               Inline helper function for ensuring correct
 208                                 pci_driver initialization and error handling.
 209 pci_resource_start()            Returns bus start address for a given PCI region
 210 pci_resource_end()              Returns bus end address for a given PCI region
 211 pci_resource_len()              Returns the byte length of a PCI region
 212 pci_set_drvdata()               Set private driver data pointer for a pci_dev
 213 pci_get_drvdata()               Return private driver data pointer for a pci_dev
 214 pci_set_mwi()                   Enable Memory-Write-Invalidate transactions.
 215 pci_clear_mwi()                 Disable Memory-Write-Invalidate transactions.
 216
 217
 218 7. Miscellaneous hints
 219 ~~~~~~~~~~~~~~~~~~~~~~
 220 When displaying PCI slot names to the user (for example when a driver wants
 221 to tell the user what card has it found), please use pci_dev->slot_name
 222 for this purpose.
 223
 224 Always refer to the PCI devices by a pointer to the pci_dev structure.
 225 All PCI layer functions use this identification and it's the only
 226 reasonable one. Don't use bus/slot/function numbers except for very
 227 special purposes -- on systems with multiple primary buses their semantics
 228 can be pretty complex.
 229
 230 If you're going to use PCI bus mastering DMA, take a look at
 231 Documentation/DMA-mapping.txt.
 232
 233
 234 8. Obsolete functions
 235 ~~~~~~~~~~~~~~~~~~~~~
 236 There are several functions kept only for compatibility with old drivers
 237 not updated to the new PCI interface. Please don't use them in new code.
 238
 239 pcibios_present()               Since ages, you don't need to test presence
 240                                 of PCI subsystem when trying to talk with it.
 241                                 If it's not there, the list of PCI devices
 242                                 is empty and all functions for searching for
 243                                 devices just return NULL.
 244 pcibios_(read|write)_*          Superseded by their pci_(read|write)_*
 245                                 counterparts.
 246 pcibios_find_*                  Superseded by their pci_find_* counterparts.