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