Commit | Line | Data |
---|---|---|
229b4e07 | 1 | .. SPDX-License-Identifier: GPL-2.0 |
1da177e4 | 2 | |
229b4e07 CD |
3 | ============================== |
4 | How To Write Linux PCI Drivers | |
5 | ============================== | |
74da15eb | 6 | |
229b4e07 CD |
7 | :Authors: - Martin Mares <mj@ucw.cz> |
8 | - Grant Grundler <grundler@parisc-linux.org> | |
1da177e4 | 9 | |
74da15eb GG |
10 | The world of PCI is vast and full of (mostly unpleasant) surprises. |
11 | Since each CPU architecture implements different chip-sets and PCI devices | |
12 | have different requirements (erm, "features"), the result is the PCI support | |
13 | in the Linux kernel is not as trivial as one would wish. This short paper | |
14 | tries to introduce all potential driver authors to Linux APIs for | |
15 | PCI device drivers. | |
16 | ||
17 | A more complete resource is the third edition of "Linux Device Drivers" | |
18 | by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. | |
19 | LDD3 is available for free (under Creative Commons License) from: | |
7ecd4a81 | 20 | https://lwn.net/Kernel/LDD3/. |
74da15eb GG |
21 | |
22 | However, keep in mind that all documents are subject to "bit rot". | |
23 | Refer to the source code if things are not working as described here. | |
24 | ||
25 | Please send questions/comments/patches about Linux PCI API to the | |
26 | "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. | |
27 | ||
1da177e4 | 28 | |
229b4e07 CD |
29 | Structure of PCI drivers |
30 | ======================== | |
74da15eb GG |
31 | PCI drivers "discover" PCI devices in a system via pci_register_driver(). |
32 | Actually, it's the other way around. When the PCI generic code discovers | |
33 | a new device, the driver with a matching "description" will be notified. | |
34 | Details on this below. | |
35 | ||
36 | pci_register_driver() leaves most of the probing for devices to | |
37 | the PCI layer and supports online insertion/removal of devices [thus | |
38 | supporting hot-pluggable PCI, CardBus, and Express-Card in a single driver]. | |
39 | pci_register_driver() call requires passing in a table of function | |
40 | pointers and thus dictates the high level structure of a driver. | |
41 | ||
42 | Once the driver knows about a PCI device and takes ownership, the | |
43 | driver generally needs to perform the following initialization: | |
1da177e4 | 44 | |
229b4e07 CD |
45 | - Enable the device |
46 | - Request MMIO/IOP resources | |
47 | - Set the DMA mask size (for both coherent and streaming DMA) | |
48 | - Allocate and initialize shared control data (pci_allocate_coherent()) | |
49 | - Access device configuration space (if needed) | |
50 | - Register IRQ handler (request_irq()) | |
51 | - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
52 | - Enable DMA/processing engines | |
74da15eb GG |
53 | |
54 | When done using the device, and perhaps the module needs to be unloaded, | |
55 | the driver needs to take the follow steps: | |
229b4e07 CD |
56 | |
57 | - Disable the device from generating IRQs | |
58 | - Release the IRQ (free_irq()) | |
59 | - Stop all DMA activity | |
60 | - Release DMA buffers (both streaming and coherent) | |
61 | - Unregister from other subsystems (e.g. scsi or netdev) | |
62 | - Release MMIO/IOP resources | |
63 | - Disable the device | |
1da177e4 | 64 | |
74da15eb GG |
65 | Most of these topics are covered in the following sections. |
66 | For the rest look at LDD3 or <linux/pci.h> . | |
1da177e4 LT |
67 | |
68 | If the PCI subsystem is not configured (CONFIG_PCI is not set), most of | |
74da15eb GG |
69 | the PCI functions described below are defined as inline functions either |
70 | completely empty or just returning an appropriate error codes to avoid | |
71 | lots of ifdefs in the drivers. | |
72 | ||
1da177e4 | 73 | |
229b4e07 CD |
74 | pci_register_driver() call |
75 | ========================== | |
1da177e4 | 76 | |
229b4e07 | 77 | PCI device drivers call ``pci_register_driver()`` during their |
74da15eb | 78 | initialization with a pointer to a structure describing the driver |
229b4e07 | 79 | (``struct pci_driver``): |
1da177e4 | 80 | |
229b4e07 CD |
81 | .. kernel-doc:: include/linux/pci.h |
82 | :functions: pci_driver | |
74da15eb | 83 | |
229b4e07 CD |
84 | The ID table is an array of ``struct pci_device_id`` entries ending with an |
85 | all-zero entry. Definitions with static const are generally preferred. | |
1da177e4 | 86 | |
229b4e07 CD |
87 | .. kernel-doc:: include/linux/mod_devicetable.h |
88 | :functions: pci_device_id | |
1da177e4 | 89 | |
229b4e07 | 90 | Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up |
74da15eb | 91 | a pci_device_id table. |
1da177e4 | 92 | |
74da15eb | 93 | New PCI IDs may be added to a device driver pci_ids table at runtime |
229b4e07 | 94 | as shown below:: |
1da177e4 | 95 | |
229b4e07 CD |
96 | echo "vendor device subvendor subdevice class class_mask driver_data" > \ |
97 | /sys/bus/pci/drivers/{driver}/new_id | |
74da15eb GG |
98 | |
99 | All fields are passed in as hexadecimal values (no leading 0x). | |
6ba18636 JD |
100 | The vendor and device fields are mandatory, the others are optional. Users |
101 | need pass only as many optional fields as necessary: | |
229b4e07 CD |
102 | |
103 | - subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) | |
104 | - class and classmask fields default to 0 | |
105 | - driver_data defaults to 0UL. | |
343b7258 | 106 | - override_only field defaults to 0. |
74da15eb | 107 | |
b41d6cf3 JD |
108 | Note that driver_data must match the value used by any of the pci_device_id |
109 | entries defined in the driver. This makes the driver_data field mandatory | |
110 | if all the pci_device_id entries have a non-zero driver_data value. | |
111 | ||
74da15eb GG |
112 | Once added, the driver probe routine will be invoked for any unclaimed |
113 | PCI devices listed in its (newly updated) pci_ids list. | |
1da177e4 LT |
114 | |
115 | When the driver exits, it just calls pci_unregister_driver() and the PCI layer | |
116 | automatically calls the remove hook for all devices handled by the driver. | |
117 | ||
74da15eb | 118 | |
229b4e07 CD |
119 | "Attributes" for driver functions/data |
120 | -------------------------------------- | |
74da15eb | 121 | |
1da177e4 LT |
122 | Please mark the initialization and cleanup functions where appropriate |
123 | (the corresponding macros are defined in <linux/init.h>): | |
124 | ||
229b4e07 | 125 | ====== ================================================= |
1da177e4 LT |
126 | __init Initialization code. Thrown away after the driver |
127 | initializes. | |
128 | __exit Exit code. Ignored for non-modular drivers. | |
229b4e07 | 129 | ====== ================================================= |
74da15eb | 130 | |
74da15eb | 131 | Tips on when/where to use the above attributes: |
229b4e07 | 132 | - The module_init()/module_exit() functions (and all |
74da15eb GG |
133 | initialization functions called _only_ from these) |
134 | should be marked __init/__exit. | |
1da177e4 | 135 | |
229b4e07 | 136 | - Do not mark the struct pci_driver. |
1da177e4 | 137 | |
229b4e07 | 138 | - Do NOT mark a function if you are not sure which mark to use. |
74da15eb GG |
139 | Better to not mark the function than mark the function wrong. |
140 | ||
141 | ||
229b4e07 CD |
142 | How to find PCI devices manually |
143 | ================================ | |
74da15eb GG |
144 | |
145 | PCI drivers should have a really good reason for not using the | |
146 | pci_register_driver() interface to search for PCI devices. | |
147 | The main reason PCI devices are controlled by multiple drivers | |
148 | is because one PCI device implements several different HW services. | |
149 | E.g. combined serial/parallel port/floppy controller. | |
150 | ||
151 | A manual search may be performed using the following constructs: | |
1da177e4 | 152 | |
229b4e07 | 153 | Searching by vendor and device ID:: |
1da177e4 LT |
154 | |
155 | struct pci_dev *dev = NULL; | |
156 | while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) | |
157 | configure_device(dev); | |
158 | ||
229b4e07 | 159 | Searching by class ID (iterate in a similar way):: |
1da177e4 LT |
160 | |
161 | pci_get_class(CLASS_ID, dev) | |
162 | ||
229b4e07 | 163 | Searching by both vendor/device and subsystem vendor/device ID:: |
1da177e4 | 164 | |
74da15eb | 165 | pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). |
1da177e4 | 166 | |
74da15eb | 167 | You can use the constant PCI_ANY_ID as a wildcard replacement for |
1da177e4 LT |
168 | VENDOR_ID or DEVICE_ID. This allows searching for any device from a |
169 | specific vendor, for example. | |
170 | ||
74da15eb | 171 | These functions are hotplug-safe. They increment the reference count on |
1da177e4 LT |
172 | the pci_dev that they return. You must eventually (possibly at module unload) |
173 | decrement the reference count on these devices by calling pci_dev_put(). | |
174 | ||
175 | ||
229b4e07 CD |
176 | Device Initialization Steps |
177 | =========================== | |
74da15eb GG |
178 | |
179 | As noted in the introduction, most PCI drivers need the following steps | |
180 | for device initialization: | |
1da177e4 | 181 | |
229b4e07 CD |
182 | - Enable the device |
183 | - Request MMIO/IOP resources | |
184 | - Set the DMA mask size (for both coherent and streaming DMA) | |
185 | - Allocate and initialize shared control data (pci_allocate_coherent()) | |
186 | - Access device configuration space (if needed) | |
187 | - Register IRQ handler (request_irq()) | |
188 | - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) | |
189 | - Enable DMA/processing engines. | |
74da15eb GG |
190 | |
191 | The driver can access PCI config space registers at any time. | |
192 | (Well, almost. When running BIST, config space can go away...but | |
193 | that will just result in a PCI Bus Master Abort and config reads | |
194 | will return garbage). | |
195 | ||
196 | ||
229b4e07 CD |
197 | Enable the PCI device |
198 | --------------------- | |
74da15eb GG |
199 | Before touching any device registers, the driver needs to enable |
200 | the PCI device by calling pci_enable_device(). This will: | |
74da15eb | 201 | |
229b4e07 CD |
202 | - wake up the device if it was in suspended state, |
203 | - allocate I/O and memory regions of the device (if BIOS did not), | |
204 | - allocate an IRQ (if BIOS did not). | |
74da15eb | 205 | |
229b4e07 CD |
206 | .. note:: |
207 | pci_enable_device() can fail! Check the return value. | |
208 | ||
209 | .. warning:: | |
210 | OS BUG: we don't check resource allocations before enabling those | |
211 | resources. The sequence would make more sense if we called | |
212 | pci_request_resources() before calling pci_enable_device(). | |
abccb9d9 | 213 | Currently, the device drivers can't detect the bug when two |
229b4e07 CD |
214 | devices have been allocated the same range. This is not a common |
215 | problem and unlikely to get fixed soon. | |
216 | ||
217 | This has been discussed before but not changed as of 2.6.19: | |
16bbbc87 | 218 | https://lore.kernel.org/r/20060302180025.GC28895@flint.arm.linux.org.uk/ |
74da15eb | 219 | |
74da15eb GG |
220 | |
221 | pci_set_master() will enable DMA by setting the bus master bit | |
222 | in the PCI_COMMAND register. It also fixes the latency timer value if | |
6a479079 BH |
223 | it's set to something bogus by the BIOS. pci_clear_master() will |
224 | disable DMA by clearing the bus master bit. | |
74da15eb GG |
225 | |
226 | If the PCI device can use the PCI Memory-Write-Invalidate transaction, | |
1da177e4 LT |
227 | call pci_set_mwi(). This enables the PCI_COMMAND bit for Mem-Wr-Inval |
228 | and also ensures that the cache line size register is set correctly. | |
74da15eb | 229 | Check the return value of pci_set_mwi() as not all architectures |
694625c0 RD |
230 | or chip-sets may support Memory-Write-Invalidate. Alternatively, |
231 | if Mem-Wr-Inval would be nice to have but is not required, call | |
232 | pci_try_set_mwi() to have the system do its best effort at enabling | |
233 | Mem-Wr-Inval. | |
74da15eb GG |
234 | |
235 | ||
229b4e07 CD |
236 | Request MMIO/IOP resources |
237 | -------------------------- | |
74da15eb GG |
238 | Memory (MMIO), and I/O port addresses should NOT be read directly |
239 | from the PCI device config space. Use the values in the pci_dev structure | |
240 | as the PCI "bus address" might have been remapped to a "host physical" | |
241 | address by the arch/chip-set specific kernel support. | |
1da177e4 | 242 | |
7d3d3254 | 243 | See Documentation/driver-api/io-mapping.rst for how to access device registers |
74da15eb GG |
244 | or device memory. |
245 | ||
246 | The device driver needs to call pci_request_region() to verify | |
247 | no other device is already using the same address resource. | |
248 | Conversely, drivers should call pci_release_region() AFTER | |
1da177e4 | 249 | calling pci_disable_device(). |
74da15eb GG |
250 | The idea is to prevent two devices colliding on the same address range. |
251 | ||
229b4e07 CD |
252 | .. tip:: |
253 | See OS BUG comment above. Currently (2.6.19), The driver can only | |
254 | determine MMIO and IO Port resource availability _after_ calling | |
255 | pci_enable_device(). | |
74da15eb GG |
256 | |
257 | Generic flavors of pci_request_region() are request_mem_region() | |
258 | (for MMIO ranges) and request_region() (for IO Port ranges). | |
259 | Use these for address resources that are not described by "normal" PCI | |
260 | BARs. | |
261 | ||
262 | Also see pci_request_selected_regions() below. | |
263 | ||
264 | ||
229b4e07 CD |
265 | Set the DMA mask size |
266 | --------------------- | |
267 | .. note:: | |
268 | If anything below doesn't make sense, please refer to | |
bffbae6d | 269 | Documentation/core-api/dma-api.rst. This section is just a reminder that |
229b4e07 CD |
270 | drivers need to indicate DMA capabilities of the device and is not |
271 | an authoritative source for DMA interfaces. | |
74da15eb GG |
272 | |
273 | While all drivers should explicitly indicate the DMA capability | |
274 | (e.g. 32 or 64 bit) of the PCI bus master, devices with more than | |
275 | 32-bit bus master capability for streaming data need the driver | |
f21949c1 | 276 | to "register" this capability by calling dma_set_mask() with |
74da15eb GG |
277 | appropriate parameters. In general this allows more efficient DMA |
278 | on systems where System RAM exists above 4G _physical_ address. | |
279 | ||
280 | Drivers for all PCI-X and PCIe compliant devices must call | |
f21949c1 | 281 | dma_set_mask() as they are 64-bit DMA devices. |
74da15eb GG |
282 | |
283 | Similarly, drivers must also "register" this capability if the device | |
05b0ebd0 CH |
284 | can directly address "coherent memory" in System RAM above 4G physical |
285 | address by calling dma_set_coherent_mask(). | |
74da15eb GG |
286 | Again, this includes drivers for all PCI-X and PCIe compliant devices. |
287 | Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are | |
288 | 64-bit DMA capable for payload ("streaming") data but not control | |
05b0ebd0 | 289 | ("coherent") data. |
74da15eb GG |
290 | |
291 | ||
229b4e07 CD |
292 | Setup shared control data |
293 | ------------------------- | |
05b0ebd0 | 294 | Once the DMA masks are set, the driver can allocate "coherent" (a.k.a. shared) |
bffbae6d | 295 | memory. See Documentation/core-api/dma-api.rst for a full description of |
74da15eb GG |
296 | the DMA APIs. This section is just a reminder that it needs to be done |
297 | before enabling DMA on the device. | |
298 | ||
299 | ||
229b4e07 CD |
300 | Initialize device registers |
301 | --------------------------- | |
74da15eb GG |
302 | Some drivers will need specific "capability" fields programmed |
303 | or other "vendor specific" register initialized or reset. | |
304 | E.g. clearing pending interrupts. | |
305 | ||
306 | ||
229b4e07 CD |
307 | Register IRQ handler |
308 | -------------------- | |
59c51591 | 309 | While calling request_irq() is the last step described here, |
74da15eb GG |
310 | this is often just another intermediate step to initialize a device. |
311 | This step can often be deferred until the device is opened for use. | |
312 | ||
313 | All interrupt handlers for IRQ lines should be registered with IRQF_SHARED | |
314 | and use the devid to map IRQs to devices (remember that all PCI IRQ lines | |
315 | can be shared). | |
316 | ||
317 | request_irq() will associate an interrupt handler and device handle | |
318 | with an interrupt number. Historically interrupt numbers represent | |
319 | IRQ lines which run from the PCI device to the Interrupt controller. | |
320 | With MSI and MSI-X (more below) the interrupt number is a CPU "vector". | |
321 | ||
322 | request_irq() also enables the interrupt. Make sure the device is | |
323 | quiesced and does not have any interrupts pending before registering | |
324 | the interrupt handler. | |
325 | ||
326 | MSI and MSI-X are PCI capabilities. Both are "Message Signaled Interrupts" | |
327 | which deliver interrupts to the CPU via a DMA write to a Local APIC. | |
328 | The fundamental difference between MSI and MSI-X is how multiple | |
329 | "vectors" get allocated. MSI requires contiguous blocks of vectors | |
330 | while MSI-X can allocate several individual ones. | |
331 | ||
c3cf2c61 CH |
332 | MSI capability can be enabled by calling pci_alloc_irq_vectors() with the |
333 | PCI_IRQ_MSI and/or PCI_IRQ_MSIX flags before calling request_irq(). This | |
334 | causes the PCI support to program CPU vector data into the PCI device | |
335 | capability registers. Many architectures, chip-sets, or BIOSes do NOT | |
336 | support MSI or MSI-X and a call to pci_alloc_irq_vectors with just | |
337 | the PCI_IRQ_MSI and PCI_IRQ_MSIX flags will fail, so try to always | |
338 | specify PCI_IRQ_LEGACY as well. | |
339 | ||
340 | Drivers that have different interrupt handlers for MSI/MSI-X and | |
341 | legacy INTx should chose the right one based on the msi_enabled | |
342 | and msix_enabled flags in the pci_dev structure after calling | |
343 | pci_alloc_irq_vectors. | |
74da15eb GG |
344 | |
345 | There are (at least) two really good reasons for using MSI: | |
229b4e07 | 346 | |
74da15eb GG |
347 | 1) MSI is an exclusive interrupt vector by definition. |
348 | This means the interrupt handler doesn't have to verify | |
349 | its device caused the interrupt. | |
350 | ||
351 | 2) MSI avoids DMA/IRQ race conditions. DMA to host memory is guaranteed | |
352 | to be visible to the host CPU(s) when the MSI is delivered. This | |
353 | is important for both data coherency and avoiding stale control data. | |
354 | This guarantee allows the driver to omit MMIO reads to flush | |
355 | the DMA stream. | |
356 | ||
357 | See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples | |
358 | of MSI/MSI-X usage. | |
359 | ||
360 | ||
229b4e07 CD |
361 | PCI device shutdown |
362 | =================== | |
74da15eb GG |
363 | |
364 | When a PCI device driver is being unloaded, most of the following | |
365 | steps need to be performed: | |
366 | ||
229b4e07 CD |
367 | - Disable the device from generating IRQs |
368 | - Release the IRQ (free_irq()) | |
369 | - Stop all DMA activity | |
05b0ebd0 | 370 | - Release DMA buffers (both streaming and coherent) |
229b4e07 CD |
371 | - Unregister from other subsystems (e.g. scsi or netdev) |
372 | - Disable device from responding to MMIO/IO Port addresses | |
373 | - Release MMIO/IO Port resource(s) | |
74da15eb GG |
374 | |
375 | ||
229b4e07 CD |
376 | Stop IRQs on the device |
377 | ----------------------- | |
74da15eb GG |
378 | How to do this is chip/device specific. If it's not done, it opens |
379 | the possibility of a "screaming interrupt" if (and only if) | |
380 | the IRQ is shared with another device. | |
381 | ||
382 | When the shared IRQ handler is "unhooked", the remaining devices | |
383 | using the same IRQ line will still need the IRQ enabled. Thus if the | |
384 | "unhooked" device asserts IRQ line, the system will respond assuming | |
385 | it was one of the remaining devices asserted the IRQ line. Since none | |
386 | of the other devices will handle the IRQ, the system will "hang" until | |
387 | it decides the IRQ isn't going to get handled and masks the IRQ (100,000 | |
388 | iterations later). Once the shared IRQ is masked, the remaining devices | |
389 | will stop functioning properly. Not a nice situation. | |
390 | ||
391 | This is another reason to use MSI or MSI-X if it's available. | |
392 | MSI and MSI-X are defined to be exclusive interrupts and thus | |
393 | are not susceptible to the "screaming interrupt" problem. | |
394 | ||
395 | ||
229b4e07 CD |
396 | Release the IRQ |
397 | --------------- | |
74da15eb GG |
398 | Once the device is quiesced (no more IRQs), one can call free_irq(). |
399 | This function will return control once any pending IRQs are handled, | |
400 | "unhook" the drivers IRQ handler from that IRQ, and finally release | |
401 | the IRQ if no one else is using it. | |
402 | ||
403 | ||
229b4e07 CD |
404 | Stop all DMA activity |
405 | --------------------- | |
74da15eb GG |
406 | It's extremely important to stop all DMA operations BEFORE attempting |
407 | to deallocate DMA control data. Failure to do so can result in memory | |
408 | corruption, hangs, and on some chip-sets a hard crash. | |
1da177e4 | 409 | |
74da15eb GG |
410 | Stopping DMA after stopping the IRQs can avoid races where the |
411 | IRQ handler might restart DMA engines. | |
412 | ||
413 | While this step sounds obvious and trivial, several "mature" drivers | |
414 | didn't get this step right in the past. | |
415 | ||
416 | ||
229b4e07 CD |
417 | Release DMA buffers |
418 | ------------------- | |
74da15eb GG |
419 | Once DMA is stopped, clean up streaming DMA first. |
420 | I.e. unmap data buffers and return buffers to "upstream" | |
421 | owners if there is one. | |
422 | ||
05b0ebd0 | 423 | Then clean up "coherent" buffers which contain the control data. |
74da15eb | 424 | |
bffbae6d | 425 | See Documentation/core-api/dma-api.rst for details on unmapping interfaces. |
74da15eb GG |
426 | |
427 | ||
229b4e07 CD |
428 | Unregister from other subsystems |
429 | -------------------------------- | |
74da15eb GG |
430 | Most low level PCI device drivers support some other subsystem |
431 | like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your | |
432 | driver isn't losing resources from that other subsystem. | |
433 | If this happens, typically the symptom is an Oops (panic) when | |
434 | the subsystem attempts to call into a driver that has been unloaded. | |
435 | ||
436 | ||
229b4e07 CD |
437 | Disable Device from responding to MMIO/IO Port addresses |
438 | -------------------------------------------------------- | |
74da15eb GG |
439 | io_unmap() MMIO or IO Port resources and then call pci_disable_device(). |
440 | This is the symmetric opposite of pci_enable_device(). | |
441 | Do not access device registers after calling pci_disable_device(). | |
442 | ||
443 | ||
229b4e07 CD |
444 | Release MMIO/IO Port Resource(s) |
445 | -------------------------------- | |
74da15eb GG |
446 | Call pci_release_region() to mark the MMIO or IO Port range as available. |
447 | Failure to do so usually results in the inability to reload the driver. | |
448 | ||
449 | ||
229b4e07 CD |
450 | How to access PCI config space |
451 | ============================== | |
74da15eb | 452 | |
229b4e07 CD |
453 | You can use `pci_(read|write)_config_(byte|word|dword)` to access the config |
454 | space of a device represented by `struct pci_dev *`. All these functions return | |
455 | 0 when successful or an error code (`PCIBIOS_...`) which can be translated to a | |
456 | text string by pcibios_strerror. Most drivers expect that accesses to valid PCI | |
1da177e4 LT |
457 | devices don't fail. |
458 | ||
74da15eb | 459 | If you don't have a struct pci_dev available, you can call |
229b4e07 | 460 | `pci_bus_(read|write)_config_(byte|word|dword)` to access a given device |
1da177e4 LT |
461 | and function on that bus. |
462 | ||
74da15eb | 463 | If you access fields in the standard portion of the config header, please |
1da177e4 LT |
464 | use symbolic names of locations and bits declared in <linux/pci.h>. |
465 | ||
74da15eb | 466 | If you need to access Extended PCI Capability registers, just call |
1da177e4 LT |
467 | pci_find_capability() for the particular capability and it will find the |
468 | corresponding register block for you. | |
469 | ||
470 | ||
229b4e07 CD |
471 | Other interesting functions |
472 | =========================== | |
1da177e4 | 473 | |
229b4e07 | 474 | ============================= ================================================ |
a37bee79 YW |
475 | pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, |
476 | bus and slot and number. If the device is | |
477 | found, its reference count is increased. | |
1da177e4 LT |
478 | pci_set_power_state() Set PCI Power Management state (0=D0 ... 3=D3) |
479 | pci_find_capability() Find specified capability in device's capability | |
480 | list. | |
1da177e4 LT |
481 | pci_resource_start() Returns bus start address for a given PCI region |
482 | pci_resource_end() Returns bus end address for a given PCI region | |
483 | pci_resource_len() Returns the byte length of a PCI region | |
484 | pci_set_drvdata() Set private driver data pointer for a pci_dev | |
485 | pci_get_drvdata() Return private driver data pointer for a pci_dev | |
486 | pci_set_mwi() Enable Memory-Write-Invalidate transactions. | |
487 | pci_clear_mwi() Disable Memory-Write-Invalidate transactions. | |
229b4e07 | 488 | ============================= ================================================ |
1da177e4 LT |
489 | |
490 | ||
229b4e07 CD |
491 | Miscellaneous hints |
492 | =================== | |
74da15eb GG |
493 | |
494 | When displaying PCI device names to the user (for example when a driver wants | |
495 | to tell the user what card has it found), please use pci_name(pci_dev). | |
1da177e4 LT |
496 | |
497 | Always refer to the PCI devices by a pointer to the pci_dev structure. | |
498 | All PCI layer functions use this identification and it's the only | |
499 | reasonable one. Don't use bus/slot/function numbers except for very | |
500 | special purposes -- on systems with multiple primary buses their semantics | |
501 | can be pretty complex. | |
502 | ||
1da177e4 LT |
503 | Don't try to turn on Fast Back to Back writes in your driver. All devices |
504 | on the bus need to be capable of doing it, so this is something which needs | |
505 | to be handled by platform and generic code, not individual drivers. | |
506 | ||
507 | ||
229b4e07 CD |
508 | Vendor and device identifications |
509 | ================================= | |
9b860b8c | 510 | |
37a9c502 MT |
511 | Do not add new device or vendor IDs to include/linux/pci_ids.h unless they |
512 | are shared across multiple drivers. You can add private definitions in | |
513 | your driver if they're helpful, or just use plain hex constants. | |
74da15eb | 514 | |
37a9c502 MT |
515 | The device IDs are arbitrary hex numbers (vendor controlled) and normally used |
516 | only in a single location, the pci_device_id table. | |
74da15eb | 517 | |
7ecd4a81 AK |
518 | Please DO submit new vendor/device IDs to https://pci-ids.ucw.cz/. |
519 | There's a mirror of the pci.ids file at https://github.com/pciutils/pciids. | |
74da15eb | 520 | |
9b860b8c | 521 | |
229b4e07 CD |
522 | Obsolete functions |
523 | ================== | |
74da15eb | 524 | |
1da177e4 LT |
525 | There are several functions which you might come across when trying to |
526 | port an old driver to the new PCI interface. They are no longer present | |
527 | in the kernel as they aren't compatible with hotplug or PCI domains or | |
528 | having sane locking. | |
529 | ||
229b4e07 | 530 | ================= =========================================== |
74da15eb GG |
531 | pci_find_device() Superseded by pci_get_device() |
532 | pci_find_subsys() Superseded by pci_get_subsys() | |
a37bee79 YW |
533 | pci_find_slot() Superseded by pci_get_domain_bus_and_slot() |
534 | pci_get_slot() Superseded by pci_get_domain_bus_and_slot() | |
229b4e07 | 535 | ================= =========================================== |
74da15eb GG |
536 | |
537 | The alternative is the traditional PCI device driver that walks PCI | |
538 | device lists. This is still possible but discouraged. | |
539 | ||
540 | ||
229b4e07 CD |
541 | MMIO Space and "Write Posting" |
542 | ============================== | |
74da15eb GG |
543 | |
544 | Converting a driver from using I/O Port space to using MMIO space | |
545 | often requires some additional changes. Specifically, "write posting" | |
546 | needs to be handled. Many drivers (e.g. tg3, acenic, sym53c8xx_2) | |
547 | already do this. I/O Port space guarantees write transactions reach the PCI | |
548 | device before the CPU can continue. Writes to MMIO space allow the CPU | |
549 | to continue before the transaction reaches the PCI device. HW weenies | |
550 | call this "Write Posting" because the write completion is "posted" to | |
551 | the CPU before the transaction has reached its destination. | |
552 | ||
553 | Thus, timing sensitive code should add readl() where the CPU is | |
554 | expected to wait before doing other work. The classic "bit banging" | |
229b4e07 | 555 | sequence works fine for I/O Port space:: |
74da15eb GG |
556 | |
557 | for (i = 8; --i; val >>= 1) { | |
558 | outb(val & 1, ioport_reg); /* write bit */ | |
559 | udelay(10); | |
560 | } | |
561 | ||
229b4e07 | 562 | The same sequence for MMIO space should be:: |
74da15eb GG |
563 | |
564 | for (i = 8; --i; val >>= 1) { | |
565 | writeb(val & 1, mmio_reg); /* write bit */ | |
566 | readb(safe_mmio_reg); /* flush posted write */ | |
567 | udelay(10); | |
568 | } | |
569 | ||
570 | It is important that "safe_mmio_reg" not have any side effects that | |
571 | interferes with the correct operation of the device. | |
572 | ||
573 | Another case to watch out for is when resetting a PCI device. Use PCI | |
574 | Configuration space reads to flush the writel(). This will gracefully | |
575 | handle the PCI master abort on all platforms if the PCI device is | |
576 | expected to not respond to a readl(). Most x86 platforms will allow | |
577 | MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage | |
578 | (e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). |