1 How To Write Linux PCI Drivers 2 3 by Martin Mares <mj@ucw.cz> on 07-Feb-2000 4 5~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6The world of PCI is vast and it's full of (mostly unpleasant) surprises. 7Different PCI devices have different requirements and different bugs -- 8because of this, the PCI support layer in Linux kernel is not as trivial 9as one would wish. This short pamphlet tries to help all potential driver 10authors to find their way through the deep forests of PCI handling. 11 12 130. Structure of PCI drivers 14~~~~~~~~~~~~~~~~~~~~~~~~~~~ 15There exist two kinds of PCI drivers: new-style ones (which leave most of 16probing for devices to the PCI layer and support online insertion and removal 17of devices [thus supporting PCI, hot-pluggable PCI and CardBus in single 18driver]) and old-style ones which just do all the probing themselves. Unless 19you have a very good reason to do so, please don't use the old way of probing 20in any new code. After the driver finds the devices it wishes to operate 21on (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 29Most of these topics are covered by the following sections, for the rest 30look at <linux/pci.h>, it's hopefully well commented. 31 32If the PCI subsystem is not configured (CONFIG_PCI is not set), most of 33the functions described below are defined as inline functions either completely 34empty or just returning an appropriate error codes to avoid lots of ifdefs 35in the drivers. 36 37 381. New-style drivers 39~~~~~~~~~~~~~~~~~~~~ 40The new-style drivers just call pci_register_driver during their initialization 41with a pointer to a structure describing the driver (struct pci_driver) which 42contains: 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 76The ID table is an array of struct pci_device_id ending with a all-zero entry. 77Each 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 86When the driver exits, it just calls pci_unregister_driver() and the PCI layer 87automatically calls the remove hook for all devices handled by the driver. 88 89Please 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 100Tips: 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 1152. How to find PCI devices manually (the old style) 116~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 117PCI drivers not using the pci_register_driver() interface search 118for PCI devices manually using the following constructs: 119 120Searching 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 126Searching by class ID (iterate in a similar way): 127 128 pci_find_class(CLASS_ID, dev) 129 130Searching 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 135VENDOR_ID or DEVICE_ID. This allows searching for any device from a 136specific vendor, for example. 137 138 In case you need to decide according to some more complex criteria, 139you 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 146For compatibility with device ordering in older kernels, you can also 147use pci_for_each_dev_reverse(dev) for walking the list in the opposite 148direction. 149 150 1513. Enabling devices 152~~~~~~~~~~~~~~~~~~~ 153 Before you do anything with the device you've found, you need to enable 154it by calling pci_enable_device() which enables I/O and memory regions of 155the device, assigns missing resources if needed and wakes up the device 156if 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() 159which enables the bus master bit in PCI_COMMAND register and also fixes 160the 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, 163call pci_set_mwi(). This enables bit PCI_COMMAND bit for Mem-Wr-Inval 164and also ensures that the cache line size register is set correctly. 165Make sure to check the return value of pci_set_mwi(), not all architectures 166may support Memory-Write-Invalidate. 167 1684. How to access PCI config space 169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 170 You can use pci_(read|write)_config_(byte|word|dword) to access the config 171space of a device represented by struct pci_dev *. All these functions return 0 172when successful or an error code (PCIBIOS_...) which can be translated to a text 173string by pcibios_strerror. Most drivers expect that accesses to valid PCI 174devices don't fail. 175 176 If you access fields in the standard portion of the config header, please 177use symbolic names of locations and bits declared in <linux/pci.h>. 178 179 If you need to access Extended PCI Capability registers, just call 180pci_find_capability() for the particular capability and it will find the 181corresponding register block for you. 182 183 1845. Addresses and interrupts 185~~~~~~~~~~~~~~~~~~~~~~~~~~~ 186 Memory and port addresses and interrupt numbers should NOT be read from the 187config space. You should use the values in the pci_dev structure as they might 188have 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 193request_mem_region() for memory regions to make sure nobody else is using the 194same device. 195 196 All interrupt handlers should be registered with SA_SHIRQ and use the devid 197to map IRQs to devices (remember that all PCI interrupts are shared). 198 199 2006. Other interesting functions 201~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 202pci_find_slot() Find pci_dev corresponding to given bus and 203 slot numbers. 204pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) 205pci_find_capability() Find specified capability in device's capability 206 list. 207pci_module_init() Inline helper function for ensuring correct 208 pci_driver initialization and error handling. 209pci_resource_start() Returns bus start address for a given PCI region 210pci_resource_end() Returns bus end address for a given PCI region 211pci_resource_len() Returns the byte length of a PCI region 212pci_set_drvdata() Set private driver data pointer for a pci_dev 213pci_get_drvdata() Return private driver data pointer for a pci_dev 214pci_set_mwi() Enable Memory-Write-Invalidate transactions. 215pci_clear_mwi() Disable Memory-Write-Invalidate transactions. 216 217 2187. Miscellaneous hints 219~~~~~~~~~~~~~~~~~~~~~~ 220When displaying PCI slot names to the user (for example when a driver wants 221to tell the user what card has it found), please use pci_dev->slot_name 222for this purpose. 223 224Always refer to the PCI devices by a pointer to the pci_dev structure. 225All PCI layer functions use this identification and it's the only 226reasonable one. Don't use bus/slot/function numbers except for very 227special purposes -- on systems with multiple primary buses their semantics 228can be pretty complex. 229 230If you're going to use PCI bus mastering DMA, take a look at 231Documentation/DMA-mapping.txt. 232 233 2348. Obsolete functions 235~~~~~~~~~~~~~~~~~~~~~ 236There are several functions kept only for compatibility with old drivers 237not updated to the new PCI interface. Please don't use them in new code. 238 239pcibios_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. 244pcibios_(read|write)_* Superseded by their pci_(read|write)_* 245 counterparts. 246pcibios_find_* Superseded by their pci_find_* counterparts. 247