blob: 3242e5c1ee9cc27330a03494a1f1d48e50cb7300 [file] [log] [blame]
Linus Torvalds1da177e2005-04-16 15:20:36 -07001 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 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 a 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 Disable the device
29
30Most of these topics are covered by the following sections, for the rest
31look at <linux/pci.h>, it's hopefully well commented.
32
33If the PCI subsystem is not configured (CONFIG_PCI is not set), most of
34the functions described below are defined as inline functions either completely
35empty or just returning an appropriate error codes to avoid lots of ifdefs
36in the drivers.
37
38
391. New-style drivers
40~~~~~~~~~~~~~~~~~~~~
41The new-style drivers just call pci_register_driver during their initialization
42with a pointer to a structure describing the driver (struct pci_driver) which
43contains:
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
75The ID table is an array of struct pci_device_id ending with a all-zero entry.
76Each 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
85Most drivers don't need to use the driver_data field. Best practice
86for use of driver_data is to use it as an index into a static list of
Adrian Bunk338cec32005-09-10 00:26:54 -070087equivalent device types, not to use it as a pointer.
Linus Torvalds1da177e2005-04-16 15:20:36 -070088
89Have a table entry {PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID, PCI_ANY_ID}
90to have probe() called for every PCI device known to the system.
91
92New PCI IDs may be added to a device driver at runtime by writing
93to the file /sys/bus/pci/drivers/{driver}/new_id. When added, the
94driver will probe for all devices it can support.
95
96echo "vendor device subvendor subdevice class class_mask driver_data" > \
97 /sys/bus/pci/drivers/{driver}/new_id
98where all fields are passed in as hexadecimal values (no leading 0x).
99Users need pass only as many fields as necessary; vendor, device,
100subvendor, and subdevice fields default to PCI_ANY_ID (FFFFFFFF),
101class and classmask fields default to 0, and driver_data defaults to
1020UL. Device drivers must initialize use_driver_data in the dynids struct
103in their pci_driver struct prior to calling pci_register_driver in order
104for the driver_data field to get passed to the driver. Otherwise, only a
1050 is passed in that field.
106
107When the driver exits, it just calls pci_unregister_driver() and the PCI layer
108automatically calls the remove hook for all devices handled by the driver.
109
110Please 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
121Tips:
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
1362. How to find PCI devices manually (the old style)
137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138PCI drivers not using the pci_register_driver() interface search
139for PCI devices manually using the following constructs:
140
141Searching by vendor and device ID:
142
143 struct pci_dev *dev = NULL;
144 while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
145 configure_device(dev);
146
147Searching by class ID (iterate in a similar way):
148
149 pci_get_class(CLASS_ID, dev)
150
151Searching by both vendor/device and subsystem vendor/device ID:
152
153 pci_get_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
156VENDOR_ID or DEVICE_ID. This allows searching for any device from a
157specific vendor, for example.
158
159 These functions are hotplug-safe. They increment the reference count on
160the pci_dev that they return. You must eventually (possibly at module unload)
161decrement the reference count on these devices by calling pci_dev_put().
162
163
1643. Enabling and disabling devices
165~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166 Before you do anything with the device you've found, you need to enable
167it by calling pci_enable_device() which enables I/O and memory regions of
168the device, allocates an IRQ if necessary, assigns missing resources if
169needed and wakes up the device if it was in suspended state. Please note
170that this function can fail.
171
172 If you want to use the device in bus mastering mode, call pci_set_master()
173which enables the bus master bit in PCI_COMMAND register and also fixes
174the latency timer value if it's set to something bogus by the BIOS.
175
176 If you want to use the PCI Memory-Write-Invalidate transaction,
177call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval
178and also ensures that the cache line size register is set correctly.
179Make sure to check the return value of pci_set_mwi(), not all architectures
180may support Memory-Write-Invalidate.
181
182 If your driver decides to stop using the device (e.g., there was an
183error while setting it up or the driver module is being unloaded), it
184should call pci_disable_device() to deallocate any IRQ resources, disable
185PCI bus-mastering, etc. You should not do anything with the device after
186calling pci_disable_device().
187
1884. How to access PCI config space
189~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
190 You can use pci_(read|write)_config_(byte|word|dword) to access the config
191space of a device represented by struct pci_dev *. All these functions return 0
192when successful or an error code (PCIBIOS_...) which can be translated to a text
193string by pcibios_strerror. Most drivers expect that accesses to valid PCI
194devices don't fail.
195
196 If you don't have a struct pci_dev available, you can call
197pci_bus_(read|write)_config_(byte|word|dword) to access a given device
198and function on that bus.
199
200 If you access fields in the standard portion of the config header, please
201use symbolic names of locations and bits declared in <linux/pci.h>.
202
203 If you need to access Extended PCI Capability registers, just call
204pci_find_capability() for the particular capability and it will find the
205corresponding register block for you.
206
207
2085. Addresses and interrupts
209~~~~~~~~~~~~~~~~~~~~~~~~~~~
210 Memory and port addresses and interrupt numbers should NOT be read from the
211config space. You should use the values in the pci_dev structure as they might
212have been remapped by the kernel.
213
214 See Documentation/IO-mapping.txt for how to access device memory.
215
Grant Grundler733a7fe2006-06-01 11:15:59 -0600216 The device driver needs to call pci_request_region() to make sure
217no other device is already using the same resource. The driver is expected
218to determine MMIO and IO Port resource availability _before_ calling
219pci_enable_device(). Conversely, drivers should call pci_release_region()
220_after_ calling pci_disable_device(). The idea is to prevent two devices
221colliding on the same address range.
222
223Generic flavors of pci_request_region() are request_mem_region()
224(for MMIO ranges) and request_region() (for IO Port ranges).
225Use these for address resources that are not described by "normal" PCI
226interfaces (e.g. BAR).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700227
228 All interrupt handlers should be registered with SA_SHIRQ and use the devid
229to map IRQs to devices (remember that all PCI interrupts are shared).
230
231
2326. Other interesting functions
233~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234pci_find_slot() Find pci_dev corresponding to given bus and
235 slot numbers.
236pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3)
237pci_find_capability() Find specified capability in device's capability
238 list.
239pci_module_init() Inline helper function for ensuring correct
240 pci_driver initialization and error handling.
241pci_resource_start() Returns bus start address for a given PCI region
242pci_resource_end() Returns bus end address for a given PCI region
243pci_resource_len() Returns the byte length of a PCI region
244pci_set_drvdata() Set private driver data pointer for a pci_dev
245pci_get_drvdata() Return private driver data pointer for a pci_dev
246pci_set_mwi() Enable Memory-Write-Invalidate transactions.
247pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
248
249
2507. Miscellaneous hints
251~~~~~~~~~~~~~~~~~~~~~~
252When displaying PCI slot names to the user (for example when a driver wants
253to tell the user what card has it found), please use pci_name(pci_dev)
254for this purpose.
255
256Always refer to the PCI devices by a pointer to the pci_dev structure.
257All PCI layer functions use this identification and it's the only
258reasonable one. Don't use bus/slot/function numbers except for very
259special purposes -- on systems with multiple primary buses their semantics
260can be pretty complex.
261
262If you're going to use PCI bus mastering DMA, take a look at
263Documentation/DMA-mapping.txt.
264
265Don't try to turn on Fast Back to Back writes in your driver. All devices
266on the bus need to be capable of doing it, so this is something which needs
267to be handled by platform and generic code, not individual drivers.
268
269
Ingo Oeser9b860b82006-04-18 11:20:55 +02002708. Vendor and device identifications
271~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272For the future, let's avoid adding device ids to include/linux/pci_ids.h.
273
274PCI_VENDOR_ID_xxx for vendors, and a hex constant for device ids.
275
276Rationale: PCI_VENDOR_ID_xxx constants are re-used, but device ids are not.
277 Further, device ids are arbitrary hex numbers, normally used only in a
278 single location, the pci_device_id table.
279
2809. Obsolete functions
Linus Torvalds1da177e2005-04-16 15:20:36 -0700281~~~~~~~~~~~~~~~~~~~~~
282There are several functions which you might come across when trying to
283port an old driver to the new PCI interface. They are no longer present
284in the kernel as they aren't compatible with hotplug or PCI domains or
285having sane locking.
286
Linus Torvalds1da177e2005-04-16 15:20:36 -0700287pci_find_device() Superseded by pci_get_device()
288pci_find_subsys() Superseded by pci_get_subsys()
Matthew Wilcoxa3ea7fb2005-03-29 19:08:48 +0100289pci_find_slot() Superseded by pci_get_slot()