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