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 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 a 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         Disable the device
  29
  30 Most of these topics are covered by the following sections, for the rest
  31 look at <linux/pci.h>, it's hopefully well commented.
  32
  33 If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
  34 the functions described below are defined as inline functions either completely
  35 empty or just returning an appropriate error codes to avoid lots of ifdefs
  36 in the drivers.
  37
  38
  39 1. New-style drivers
  40 ~~~~~~~~~~~~~~~~~~~~
  41 The new-style drivers just call pci_register_driver during their initialization
  42 with a pointer to a structure describing the driver (struct pci_driver) which
  43 contains:
  44
  45         name            Name of the driver
  46         id_table        Pointer to table of device ID's the driver is
  47                         interested in.  Most drivers should export this
  48                         table using MODULE_DEVICE_TABLE(pci,...).
  49         probe           Pointer to a probing function which gets called (during
  50                         execution of pci_register_driver for already existing
  51                         devices or later if a new device gets inserted) for all
  52                         PCI devices which match the ID table and are not handled
  53                         by the other drivers yet. This function gets passed a
  54                         pointer to the pci_dev structure representing the device
  55                         and also which entry in the ID table did the device
  56                         match. It returns zero when the driver has accepted the
  57                         device or an error code (negative number) otherwise.
  58                         This function always gets called from process context,
  59                         so it can sleep.
  60         remove          Pointer to a function which gets called whenever a
  61                         device being handled by this driver is removed (either
  62                         during deregistration of the driver or when it's
  63                         manually pulled out of a hot-pluggable slot). This
  64                         function always gets called from process context, so it
  65                         can sleep.
  66         save_state      Save a device's state before it's suspend.
  67         suspend         Put device into low power state.
  68         resume          Wake device from low power state.
  69         enable_wake     Enable device to generate wake events from a low power
  70                         state.
  71
  72                         (Please see Documentation/power/pci.txt for descriptions
  73                         of PCI Power Management and the related functions)
  74
  75 The ID table is an array of struct pci_device_id ending with a all-zero entry.
  76 Each entry consists of:
  77
  78         vendor, device  Vendor and device ID to match (or PCI_ANY_ID)
  79         subvendor,      Subsystem vendor and device ID to match (or PCI_ANY_ID)
  80         subdevice
  81         class,          Device class to match. The class_mask tells which bits
  82         class_mask      of the class are honored during the comparison.
  83         driver_data     Data private to the driver.
  84
  85 Most drivers don't need to use the driver_data field.  Best practice
  86 for use of driver_data is to use it as an index into a static list of
  87 equivalant device types, not to use it as a pointer.
  88
  89 Have a table entry {PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID}
  90 to have probe() called for every PCI device known to the system.
  91
  92 New PCI IDs may be added to a device driver at runtime by writing
  93 to the file /sys/bus/pci/drivers/{driver}/new_id.  When added, the
  94 driver will probe for all devices it can support.
  95
  96 echo "vendor device subvendor subdevice class class_mask driver_data" > \
  97  /sys/bus/pci/drivers/{driver}/new_id
  98 where all fields are passed in as hexadecimal values (no leading 0x).
  99 Users need pass only as many fields as necessary; vendor, device,
 100 subvendor, and subdevice fields default to PCI_ANY_ID (FFFFFFFF),
 101 class and classmask fields default to 0, and driver_data defaults to
 102 0UL.  Device drivers must call
 103    pci_dynids_set_use_driver_data(pci_driver *, 1)
 104 in order for the driver_data field to get passed to the driver.
 105 Otherwise, only a 0 is passed in that field.
 106
 107 When the driver exits, it just calls pci_unregister_driver() and the PCI layer
 108 automatically calls the remove hook for all devices handled by the driver.
 109
 110 Please mark the initialization and cleanup functions where appropriate
 111 (the corresponding macros are defined in <linux/init.h>):
 112
 113         __init          Initialization code. Thrown away after the driver
 114                         initializes.
 115         __exit          Exit code. Ignored for non-modular drivers.
 116         __devinit       Device initialization code. Identical to __init if
 117                         the kernel is not compiled with CONFIG_HOTPLUG, normal
 118                         function otherwise.
 119         __devexit       The same for __exit.
 120
 121 Tips:
 122         The module_init()/module_exit() functions (and all initialization
 123         functions called only from these) should be marked __init/exit.
 124         The struct pci_driver shouldn't be marked with any of these tags.
 125         The ID table array should be marked __devinitdata.
 126         The probe() and remove() functions (and all initialization
 127         functions called only from these) should be marked __devinit/exit.
 128         If you are sure the driver is not a hotplug driver then use only
 129         __init/exit __initdata/exitdata.
 130
 131         Pointers to functions marked as __devexit must be created using
 132         __devexit_p(function_name).  That will generate the function
 133         name or NULL if the __devexit function will be discarded.
 134
 135
 136 2. How to find PCI devices manually (the old style)
 137 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 138 PCI drivers not using the pci_register_driver() interface search
 139 for PCI devices manually using the following constructs:
 140
 141 Searching by vendor and device ID:
 142
 143         struct pci_dev *dev = NULL;
 144         while (dev = pci_find_device(VENDOR_ID, DEVICE_ID, dev))
 145                 configure_device(dev);
 146
 147 Searching by class ID (iterate in a similar way):
 148
 149         pci_find_class(CLASS_ID, dev)
 150
 151 Searching by both vendor/device and subsystem vendor/device ID:
 152
 153         pci_find_subsys(VENDOR_ID, DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
 154
 155    You can use the constant PCI_ANY_ID as a wildcard replacement for
 156 VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
 157 specific vendor, for example.
 158
 159 Note that these functions are not hotplug-safe.  Their hotplug-safe
 160 replacements are pci_get_device(), pci_get_class() and pci_get_subsys().
 161 They increment the reference count on the pci_dev that they return.
 162 You must eventually (possibly at module unload) decrement the reference
 163 count on these devices by calling pci_dev_put().
 164
 165
 166 3. Enabling and disabling devices
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168    Before you do anything with the device you've found, you need to enable
 169 it by calling pci_enable_device() which enables I/O and memory regions of
 170 the device, allocates an IRQ if necessary, assigns missing resources if
 171 needed and wakes up the device if it was in suspended state. Please note
 172 that this function can fail.
 173
 174    If you want to use the device in bus mastering mode, call pci_set_master()
 175 which enables the bus master bit in PCI_COMMAND register and also fixes
 176 the latency timer value if it's set to something bogus by the BIOS.
 177
 178    If you want to use the PCI Memory-Write-Invalidate transaction,
 179 call pci_set_mwi().  This enables the PCI_COMMAND bit for Mem-Wr-Inval
 180 and also ensures that the cache line size register is set correctly.
 181 Make sure to check the return value of pci_set_mwi(), not all architectures
 182 may support Memory-Write-Invalidate.
 183
 184    If your driver decides to stop using the device (e.g., there was an
 185 error while setting it up or the driver module is being unloaded), it
 186 should call pci_disable_device() to deallocate any IRQ resources, disable
 187 PCI bus-mastering, etc.  You should not do anything with the device after
 188 calling pci_disable_device().
 189
 190 4. How to access PCI config space
 191 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 192    You can use pci_(read|write)_config_(byte|word|dword) to access the config
 193 space of a device represented by struct pci_dev *. All these functions return 0
 194 when successful or an error code (PCIBIOS_...) which can be translated to a text
 195 string by pcibios_strerror. Most drivers expect that accesses to valid PCI
 196 devices don't fail.
 197
 198    If you don't have a struct pci_dev available, you can call
 199 pci_bus_(read|write)_config_(byte|word|dword) to access a given device
 200 and function on that bus.
 201
 202    If you access fields in the standard portion of the config header, please
 203 use symbolic names of locations and bits declared in <linux/pci.h>.
 204
 205    If you need to access Extended PCI Capability registers, just call
 206 pci_find_capability() for the particular capability and it will find the
 207 corresponding register block for you.
 208
 209
 210 5. Addresses and interrupts
 211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 212    Memory and port addresses and interrupt numbers should NOT be read from the
 213 config space. You should use the values in the pci_dev structure as they might
 214 have been remapped by the kernel.
 215
 216    See Documentation/IO-mapping.txt for how to access device memory.
 217
 218    You still need to call request_region() for I/O regions and
 219 request_mem_region() for memory regions to make sure nobody else is using the
 220 same device.
 221
 222    All interrupt handlers should be registered with SA_SHIRQ and use the devid
 223 to map IRQs to devices (remember that all PCI interrupts are shared).
 224
 225
 226 6. Other interesting functions
 227 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 228 pci_find_slot()                 Find pci_dev corresponding to given bus and
 229                                 slot numbers.
 230 pci_set_power_state()           Set PCI Power Management state (0=D0 ... 3=D3)
 231 pci_find_capability()           Find specified capability in device's capability
 232                                 list.
 233 pci_module_init()               Inline helper function for ensuring correct
 234                                 pci_driver initialization and error handling.
 235 pci_resource_start()            Returns bus start address for a given PCI region
 236 pci_resource_end()              Returns bus end address for a given PCI region
 237 pci_resource_len()              Returns the byte length of a PCI region
 238 pci_set_drvdata()               Set private driver data pointer for a pci_dev
 239 pci_get_drvdata()               Return private driver data pointer for a pci_dev
 240 pci_set_mwi()                   Enable Memory-Write-Invalidate transactions.
 241 pci_clear_mwi()                 Disable Memory-Write-Invalidate transactions.
 242
 243
 244 7. Miscellaneous hints
 245 ~~~~~~~~~~~~~~~~~~~~~~
 246 When displaying PCI slot names to the user (for example when a driver wants
 247 to tell the user what card has it found), please use pci_name(pci_dev)
 248 for this purpose.
 249
 250 Always refer to the PCI devices by a pointer to the pci_dev structure.
 251 All PCI layer functions use this identification and it's the only
 252 reasonable one. Don't use bus/slot/function numbers except for very
 253 special purposes -- on systems with multiple primary buses their semantics
 254 can be pretty complex.
 255
 256 If you're going to use PCI bus mastering DMA, take a look at
 257 Documentation/DMA-mapping.txt.
 258
 259 Don't try to turn on Fast Back to Back writes in your driver.  All devices
 260 on the bus need to be capable of doing it, so this is something which needs
 261 to be handled by platform and generic code, not individual drivers.
 262
 263
 264 8. Obsolete functions
 265 ~~~~~~~~~~~~~~~~~~~~~
 266 There are several functions which you might come across when trying to
 267 port an old driver to the new PCI interface.  They are no longer present
 268 in the kernel as they aren't compatible with hotplug or PCI domains or
 269 having sane locking.
 270
 271 pcibios_present() and           Since ages, you don't need to test presence
 272 pci_present()                   of PCI subsystem when trying to talk to it.
 273                                 If it's not there, the list of PCI devices
 274                                 is empty and all functions for searching for
 275                                 devices just return NULL.
 276 pcibios_(read|write)_*          Superseded by their pci_(read|write)_*
 277                                 counterparts.
 278 pcibios_find_*                  Superseded by their pci_find_* counterparts.
 279 pci_for_each_dev()              Superseded by pci_find_device()
 280 pci_for_each_dev_reverse()      Superseded by pci_find_device_reverse()
 281 pci_for_each_bus()              Superseded by pci_find_next_bus()
 282 pci_find_device()               Superseded by pci_get_device()
 283 pci_find_subsys()               Superseded by pci_get_subsys()
 284 pcibios_find_class()            Superseded by pci_find_class()
 285 pci_(read|write)_*_nodev()      Superseded by pci_bus_(read|write)_*()