| @@ -1,10 +1,12 @@ |
| 1 | +.. SPDX-License-Identifier: GPL-2.0 |
| 1 | 2 | |
| 2 | | − How To Write Linux PCI Drivers |
| 3 | +============================== |
| 4 | +How To Write Linux PCI Drivers |
| 5 | +============================== |
| 3 | 6 | |
| 4 | | − by Martin Mares <mj@ucw.cz> on 07-Feb-2000 |
| 5 | | − updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006 |
| 7 | +:Authors: - Martin Mares <mj@ucw.cz> |
| 8 | + - Grant Grundler <grundler@parisc-linux.org> |
| 6 | 9 | |
| 7 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 8 | 10 | The world of PCI is vast and full of (mostly unpleasant) surprises. |
| 9 | 11 | Since each CPU architecture implements different chip-sets and PCI devices |
| 10 | 12 | have different requirements (erm, "features"), the result is the PCI support |
| @@ -15,8 +17,7 @@ PCI device drivers. · 4 unmodified lines |
| 15 | 17 | A more complete resource is the third edition of "Linux Device Drivers" |
| 16 | 18 | by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman. |
| 17 | 19 | LDD3 is available for free (under Creative Commons License) from: |
| 18 | | − |
| 19 | | − http://lwn.net/Kernel/LDD3/ |
| 20 | +http://lwn.net/Kernel/LDD3/. |
| 20 | 21 | |
| 21 | 22 | However, keep in mind that all documents are subject to "bit rot". |
| 22 | 23 | Refer to the source code if things are not working as described here. |
| @@ -25,9 +26,8 @@ Please send questions/comments/patches about Linux PCI API to the · 2 unmodified lines |
| 25 | 26 | "Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list. |
| 26 | 27 | |
| 27 | 28 | |
| 28 | | − |
| 29 | | −0. Structure of PCI drivers |
| 30 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 29 | +Structure of PCI drivers |
| 30 | +======================== |
| 31 | 31 | PCI drivers "discover" PCI devices in a system via pci_register_driver(). |
| 32 | 32 | Actually, it's the other way around. When the PCI generic code discovers |
| 33 | 33 | a new device, the driver with a matching "description" will be notified. |
| @@ -42,24 +42,25 @@ pointers and thus dictates the high level structure of a driver. · 8 unmodified lines |
| 42 | 42 | Once the driver knows about a PCI device and takes ownership, the |
| 43 | 43 | driver generally needs to perform the following initialization: |
| 44 | 44 | |
| 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 |
| 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 |
| 53 | 53 | |
| 54 | 54 | When done using the device, and perhaps the module needs to be unloaded, |
| 55 | 55 | the driver needs to take the follow steps: |
| 56 | | − Disable the device from generating IRQs |
| 57 | | − Release the IRQ (free_irq()) |
| 58 | | − Stop all DMA activity |
| 59 | | − Release DMA buffers (both streaming and coherent) |
| 60 | | − Unregister from other subsystems (e.g. scsi or netdev) |
| 61 | | − Release MMIO/IOP resources |
| 62 | | − Disable the device |
| 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 |
| 63 | 64 | |
| 64 | 65 | Most of these topics are covered in the following sections. |
| 65 | 66 | For the rest look at LDD3 or <linux/pci.h> . |
| @@ -70,99 +71,38 @@ completely empty or just returning an appropriate error codes to avoid · 4 unmodified lines |
| 70 | 71 | lots of ifdefs in the drivers. |
| 71 | 72 | |
| 72 | 73 | |
| 74 | +pci_register_driver() call |
| 75 | +========================== |
| 73 | 76 | |
| 74 | | −1. pci_register_driver() call |
| 75 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 76 | | − |
| 77 | | −PCI device drivers call pci_register_driver() during their |
| 77 | +PCI device drivers call ``pci_register_driver()`` during their |
| 78 | 78 | initialization with a pointer to a structure describing the driver |
| 79 | | −(struct pci_driver): |
| 80 | | − |
| 81 | | − field name Description |
| 82 | | − ---------- ------------------------------------------------------ |
| 83 | | − id_table Pointer to table of device ID's the driver is |
| 84 | | − interested in. Most drivers should export this |
| 85 | | − table using MODULE_DEVICE_TABLE(pci,...). |
| 86 | | − |
| 87 | | − probe This probing function gets called (during execution |
| 88 | | − of pci_register_driver() for already existing |
| 89 | | − devices or later if a new device gets inserted) for |
| 90 | | − all PCI devices which match the ID table and are not |
| 91 | | − "owned" by the other drivers yet. This function gets |
| 92 | | − passed a "struct pci_dev *" for each device whose |
| 93 | | − entry in the ID table matches the device. The probe |
| 94 | | − function returns zero when the driver chooses to |
| 95 | | − take "ownership" of the device or an error code |
| 96 | | − (negative number) otherwise. |
| 97 | | − The probe function always gets called from process |
| 98 | | − context, so it can sleep. |
| 99 | | − |
| 100 | | − remove The remove() function gets called whenever a device |
| 101 | | − being handled by this driver is removed (either during |
| 102 | | − deregistration of the driver or when it's manually |
| 103 | | − pulled out of a hot-pluggable slot). |
| 104 | | − The remove function always gets called from process |
| 105 | | − context, so it can sleep. |
| 106 | | − |
| 107 | | − suspend Put device into low power state. |
| 108 | | − suspend_late Put device into low power state. |
| 109 | | − |
| 110 | | − resume_early Wake device from low power state. |
| 111 | | − resume Wake device from low power state. |
| 112 | | − |
| 113 | | − (Please see Documentation/power/pci.txt for descriptions |
| 114 | | − of PCI Power Management and the related functions.) |
| 115 | | − |
| 116 | | − shutdown Hook into reboot_notifier_list (kernel/sys.c). |
| 117 | | − Intended to stop any idling DMA operations. |
| 118 | | − Useful for enabling wake-on-lan (NIC) or changing |
| 119 | | − the power state of a device before reboot. |
| 120 | | − e.g. drivers/net/e100.c. |
| 121 | | − |
| 122 | | − err_handler See Documentation/PCI/pci-error-recovery.txt |
| 123 | | − |
| 124 | | − |
| 125 | | −The ID table is an array of struct pci_device_id entries ending with an |
| 126 | | −all-zero entry. Definitions with static const are generally preferred. |
| 127 | | − |
| 128 | | −Each entry consists of: |
| 129 | | − |
| 130 | | − vendor,device Vendor and device ID to match (or PCI_ANY_ID) |
| 79 | +(``struct pci_driver``): |
| 131 | 80 | |
| 132 | | − subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID) |
| 133 | | − subdevice, |
| 81 | +.. kernel-doc:: include/linux/pci.h |
| 82 | + :functions: pci_driver |
| 134 | 83 | |
| 135 | | − class Device class, subclass, and "interface" to match. |
| 136 | | − See Appendix D of the PCI Local Bus Spec or |
| 137 | | − include/linux/pci_ids.h for a full list of classes. |
| 138 | | − Most drivers do not need to specify class/class_mask |
| 139 | | − as vendor/device is normally sufficient. |
| 140 | | − |
| 141 | | − class_mask limit which sub-fields of the class field are compared. |
| 142 | | − See drivers/scsi/sym53c8xx_2/ for example of usage. |
| 143 | | − |
| 144 | | − driver_data Data private to the driver. |
| 145 | | − Most drivers don't need to use driver_data field. |
| 146 | | − Best practice is to use driver_data as an index |
| 147 | | − into a static list of equivalent device types, |
| 148 | | − instead of using it as a pointer. |
| 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. |
| 149 | 86 | |
| 87 | +.. kernel-doc:: include/linux/mod_devicetable.h |
| 88 | + :functions: pci_device_id |
| 150 | 89 | |
| 151 | | −Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up |
| 90 | +Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up |
| 152 | 91 | a pci_device_id table. |
| 153 | 92 | |
| 154 | 93 | New PCI IDs may be added to a device driver pci_ids table at runtime |
| 155 | | −as shown below: |
| 94 | +as shown below:: |
| 156 | 95 | |
| 157 | | −echo "vendor device subvendor subdevice class class_mask driver_data" > \ |
| 158 | | −/sys/bus/pci/drivers/{driver}/new_id |
| 96 | + echo "vendor device subvendor subdevice class class_mask driver_data" > \ |
| 97 | + /sys/bus/pci/drivers/{driver}/new_id |
| 159 | 98 | |
| 160 | 99 | All fields are passed in as hexadecimal values (no leading 0x). |
| 161 | 100 | The vendor and device fields are mandatory, the others are optional. Users |
| 162 | 101 | need pass only as many optional fields as necessary: |
| 163 | | − o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF) |
| 164 | | − o class and classmask fields default to 0 |
| 165 | | − o driver_data defaults to 0UL. |
| 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. |
| 166 | 106 | |
| 167 | 107 | Note that driver_data must match the value used by any of the pci_device_id |
| 168 | 108 | entries defined in the driver. This makes the driver_data field mandatory |
| @@ -175,29 +115,31 @@ When the driver exits, it just calls pci_unregister_driver() and the PCI layer · 6 unmodified lines |
| 175 | 115 | automatically calls the remove hook for all devices handled by the driver. |
| 176 | 116 | |
| 177 | 117 | |
| 178 | | −1.1 "Attributes" for driver functions/data |
| 118 | +"Attributes" for driver functions/data |
| 119 | +-------------------------------------- |
| 179 | 120 | |
| 180 | 121 | Please mark the initialization and cleanup functions where appropriate |
| 181 | 122 | (the corresponding macros are defined in <linux/init.h>): |
| 182 | 123 | |
| 124 | + ====== ================================================= |
| 183 | 125 | __init Initialization code. Thrown away after the driver |
| 184 | 126 | initializes. |
| 185 | 127 | __exit Exit code. Ignored for non-modular drivers. |
| 128 | + ====== ================================================= |
| 186 | 129 | |
| 187 | 130 | Tips on when/where to use the above attributes: |
| 188 | | − o The module_init()/module_exit() functions (and all |
| 131 | + - The module_init()/module_exit() functions (and all |
| 189 | 132 | initialization functions called _only_ from these) |
| 190 | 133 | should be marked __init/__exit. |
| 191 | 134 | |
| 192 | | − o Do not mark the struct pci_driver. |
| 135 | + - Do not mark the struct pci_driver. |
| 193 | 136 | |
| 194 | | − o Do NOT mark a function if you are not sure which mark to use. |
| 137 | + - Do NOT mark a function if you are not sure which mark to use. |
| 195 | 138 | Better to not mark the function than mark the function wrong. |
| 196 | 139 | |
| 197 | 140 | |
| 198 | | − |
| 199 | | −2. How to find PCI devices manually |
| 200 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 141 | +How to find PCI devices manually |
| 142 | +================================ |
| 201 | 143 | |
| 202 | 144 | PCI drivers should have a really good reason for not using the |
| 203 | 145 | pci_register_driver() interface to search for PCI devices. |
| @@ -207,17 +149,17 @@ E.g. combined serial/parallel port/floppy controller. · 3 unmodified lines |
| 207 | 149 | |
| 208 | 150 | A manual search may be performed using the following constructs: |
| 209 | 151 | |
| 210 | | −Searching by vendor and device ID: |
| 152 | +Searching by vendor and device ID:: |
| 211 | 153 | |
| 212 | 154 | struct pci_dev *dev = NULL; |
| 213 | 155 | while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev)) |
| 214 | 156 | configure_device(dev); |
| 215 | 157 | |
| 216 | | −Searching by class ID (iterate in a similar way): |
| 158 | +Searching by class ID (iterate in a similar way):: |
| 217 | 159 | |
| 218 | 160 | pci_get_class(CLASS_ID, dev) |
| 219 | 161 | |
| 220 | | −Searching by both vendor/device and subsystem vendor/device ID: |
| 162 | +Searching by both vendor/device and subsystem vendor/device ID:: |
| 221 | 163 | |
| 222 | 164 | pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev). |
| 223 | 165 | |
| @@ -230,21 +172,20 @@ the pci_dev that they return. You must eventually (possibly at module unload) · 6 unmodified lines |
| 230 | 172 | decrement the reference count on these devices by calling pci_dev_put(). |
| 231 | 173 | |
| 232 | 174 | |
| 233 | | − |
| 234 | | −3. Device Initialization Steps |
| 235 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 175 | +Device Initialization Steps |
| 176 | +=========================== |
| 236 | 177 | |
| 237 | 178 | As noted in the introduction, most PCI drivers need the following steps |
| 238 | 179 | for device initialization: |
| 239 | 180 | |
| 240 | | − Enable the device |
| 241 | | − Request MMIO/IOP resources |
| 242 | | − Set the DMA mask size (for both coherent and streaming DMA) |
| 243 | | − Allocate and initialize shared control data (pci_allocate_coherent()) |
| 244 | | − Access device configuration space (if needed) |
| 245 | | − Register IRQ handler (request_irq()) |
| 246 | | − Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) |
| 247 | | − Enable DMA/processing engines. |
| 181 | + - Enable the device |
| 182 | + - Request MMIO/IOP resources |
| 183 | + - Set the DMA mask size (for both coherent and streaming DMA) |
| 184 | + - Allocate and initialize shared control data (pci_allocate_coherent()) |
| 185 | + - Access device configuration space (if needed) |
| 186 | + - Register IRQ handler (request_irq()) |
| 187 | + - Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip) |
| 188 | + - Enable DMA/processing engines. |
| 248 | 189 | |
| 249 | 190 | The driver can access PCI config space registers at any time. |
| 250 | 191 | (Well, almost. When running BIST, config space can go away...but |
| @@ -252,26 +193,29 @@ that will just result in a PCI Bus Master Abort and config reads · 1 unmodified line |
| 252 | 193 | will return garbage). |
| 253 | 194 | |
| 254 | 195 | |
| 255 | | −3.1 Enable the PCI device |
| 256 | | −~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 196 | +Enable the PCI device |
| 197 | +--------------------- |
| 257 | 198 | Before touching any device registers, the driver needs to enable |
| 258 | 199 | the PCI device by calling pci_enable_device(). This will: |
| 259 | | − o wake up the device if it was in suspended state, |
| 260 | | − o allocate I/O and memory regions of the device (if BIOS did not), |
| 261 | | − o allocate an IRQ (if BIOS did not). |
| 262 | 200 | |
| 263 | | −NOTE: pci_enable_device() can fail! Check the return value. |
| 201 | + - wake up the device if it was in suspended state, |
| 202 | + - allocate I/O and memory regions of the device (if BIOS did not), |
| 203 | + - allocate an IRQ (if BIOS did not). |
| 264 | 204 | |
| 265 | | −[ OS BUG: we don't check resource allocations before enabling those |
| 266 | | − resources. The sequence would make more sense if we called |
| 267 | | − pci_request_resources() before calling pci_enable_device(). |
| 268 | | − Currently, the device drivers can't detect the bug when when two |
| 269 | | − devices have been allocated the same range. This is not a common |
| 270 | | − problem and unlikely to get fixed soon. |
| 205 | +.. note:: |
| 206 | + pci_enable_device() can fail! Check the return value. |
| 207 | + |
| 208 | +.. warning:: |
| 209 | + OS BUG: we don't check resource allocations before enabling those |
| 210 | + resources. The sequence would make more sense if we called |
| 211 | + pci_request_resources() before calling pci_enable_device(). |
| 212 | + Currently, the device drivers can't detect the bug when when two |
| 213 | + devices have been allocated the same range. This is not a common |
| 214 | + problem and unlikely to get fixed soon. |
| 215 | + |
| 216 | + This has been discussed before but not changed as of 2.6.19: |
| 217 | + http://lkml.org/lkml/2006/3/2/194 |
| 271 | 218 | |
| 272 | | − This has been discussed before but not changed as of 2.6.19: |
| 273 | | − http://lkml.org/lkml/2006/3/2/194 |
| 274 | | −] |
| 275 | 219 | |
| 276 | 220 | pci_set_master() will enable DMA by setting the bus master bit |
| 277 | 221 | in the PCI_COMMAND register. It also fixes the latency timer value if |
| @@ -288,8 +232,8 @@ pci_try_set_mwi() to have the system do its best effort at enabling · 10 unmodified lines |
| 288 | 232 | Mem-Wr-Inval. |
| 289 | 233 | |
| 290 | 234 | |
| 291 | | −3.2 Request MMIO/IOP resources |
| 292 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 235 | +Request MMIO/IOP resources |
| 236 | +-------------------------- |
| 293 | 237 | Memory (MMIO), and I/O port addresses should NOT be read directly |
| 294 | 238 | from the PCI device config space. Use the values in the pci_dev structure |
| 295 | 239 | as the PCI "bus address" might have been remapped to a "host physical" |
| @@ -304,9 +248,10 @@ Conversely, drivers should call pci_release_region() AFTER · 8 unmodified lines |
| 304 | 248 | calling pci_disable_device(). |
| 305 | 249 | The idea is to prevent two devices colliding on the same address range. |
| 306 | 250 | |
| 307 | | −[ See OS BUG comment above. Currently (2.6.19), The driver can only |
| 308 | | − determine MMIO and IO Port resource availability _after_ calling |
| 309 | | − pci_enable_device(). ] |
| 251 | +.. tip:: |
| 252 | + See OS BUG comment above. Currently (2.6.19), The driver can only |
| 253 | + determine MMIO and IO Port resource availability _after_ calling |
| 254 | + pci_enable_device(). |
| 310 | 255 | |
| 311 | 256 | Generic flavors of pci_request_region() are request_mem_region() |
| 312 | 257 | (for MMIO ranges) and request_region() (for IO Port ranges). |
| @@ -316,12 +261,13 @@ BARs. · 3 unmodified lines |
| 316 | 261 | Also see pci_request_selected_regions() below. |
| 317 | 262 | |
| 318 | 263 | |
| 319 | | −3.3 Set the DMA mask size |
| 320 | | −~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 321 | | −[ If anything below doesn't make sense, please refer to |
| 322 | | − Documentation/DMA-API.txt. This section is just a reminder that |
| 323 | | − drivers need to indicate DMA capabilities of the device and is not |
| 324 | | − an authoritative source for DMA interfaces. ] |
| 264 | +Set the DMA mask size |
| 265 | +--------------------- |
| 266 | +.. note:: |
| 267 | + If anything below doesn't make sense, please refer to |
| 268 | + Documentation/DMA-API.txt. This section is just a reminder that |
| 269 | + drivers need to indicate DMA capabilities of the device and is not |
| 270 | + an authoritative source for DMA interfaces. |
| 325 | 271 | |
| 326 | 272 | While all drivers should explicitly indicate the DMA capability |
| 327 | 273 | (e.g. 32 or 64 bit) of the PCI bus master, devices with more than |
| @@ -342,23 +288,23 @@ Many 64-bit "PCI" devices (before PCI-X) and some PCI-X devices are · 14 unmodified lines |
| 342 | 288 | ("consistent") data. |
| 343 | 289 | |
| 344 | 290 | |
| 345 | | −3.4 Setup shared control data |
| 346 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 291 | +Setup shared control data |
| 292 | +------------------------- |
| 347 | 293 | Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared) |
| 348 | 294 | memory. See Documentation/DMA-API.txt for a full description of |
| 349 | 295 | the DMA APIs. This section is just a reminder that it needs to be done |
| 350 | 296 | before enabling DMA on the device. |
| 351 | 297 | |
| 352 | 298 | |
| 353 | | −3.5 Initialize device registers |
| 354 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 299 | +Initialize device registers |
| 300 | +--------------------------- |
| 355 | 301 | Some drivers will need specific "capability" fields programmed |
| 356 | 302 | or other "vendor specific" register initialized or reset. |
| 357 | 303 | E.g. clearing pending interrupts. |
| 358 | 304 | |
| 359 | 305 | |
| 360 | | −3.6 Register IRQ handler |
| 361 | | −~~~~~~~~~~~~~~~~~~~~~~~~ |
| 306 | +Register IRQ handler |
| 307 | +-------------------- |
| 362 | 308 | While calling request_irq() is the last step described here, |
| 363 | 309 | this is often just another intermediate step to initialize a device. |
| 364 | 310 | This step can often be deferred until the device is opened for use. |
| @@ -396,6 +342,7 @@ and msix_enabled flags in the pci_dev structure after calling · 31 unmodified lines |
| 396 | 342 | pci_alloc_irq_vectors. |
| 397 | 343 | |
| 398 | 344 | There are (at least) two really good reasons for using MSI: |
| 345 | + |
| 399 | 346 | 1) MSI is an exclusive interrupt vector by definition. |
| 400 | 347 | This means the interrupt handler doesn't have to verify |
| 401 | 348 | its device caused the interrupt. |
| @@ -410,24 +357,23 @@ See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples · 8 unmodified lines |
| 410 | 357 | of MSI/MSI-X usage. |
| 411 | 358 | |
| 412 | 359 | |
| 413 | | − |
| 414 | | −4. PCI device shutdown |
| 415 | | −~~~~~~~~~~~~~~~~~~~~~~~ |
| 360 | +PCI device shutdown |
| 361 | +=================== |
| 416 | 362 | |
| 417 | 363 | When a PCI device driver is being unloaded, most of the following |
| 418 | 364 | steps need to be performed: |
| 419 | 365 | |
| 420 | | − Disable the device from generating IRQs |
| 421 | | − Release the IRQ (free_irq()) |
| 422 | | − Stop all DMA activity |
| 423 | | − Release DMA buffers (both streaming and consistent) |
| 424 | | − Unregister from other subsystems (e.g. scsi or netdev) |
| 425 | | − Disable device from responding to MMIO/IO Port addresses |
| 426 | | − Release MMIO/IO Port resource(s) |
| 366 | + - Disable the device from generating IRQs |
| 367 | + - Release the IRQ (free_irq()) |
| 368 | + - Stop all DMA activity |
| 369 | + - Release DMA buffers (both streaming and consistent) |
| 370 | + - Unregister from other subsystems (e.g. scsi or netdev) |
| 371 | + - Disable device from responding to MMIO/IO Port addresses |
| 372 | + - Release MMIO/IO Port resource(s) |
| 427 | 373 | |
| 428 | 374 | |
| 429 | | −4.1 Stop IRQs on the device |
| 430 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 375 | +Stop IRQs on the device |
| 376 | +----------------------- |
| 431 | 377 | How to do this is chip/device specific. If it's not done, it opens |
| 432 | 378 | the possibility of a "screaming interrupt" if (and only if) |
| 433 | 379 | the IRQ is shared with another device. |
| @@ -446,16 +392,16 @@ MSI and MSI-X are defined to be exclusive interrupts and thus · 12 unmodified lines |
| 446 | 392 | are not susceptible to the "screaming interrupt" problem. |
| 447 | 393 | |
| 448 | 394 | |
| 449 | | −4.2 Release the IRQ |
| 450 | | −~~~~~~~~~~~~~~~~~~~ |
| 395 | +Release the IRQ |
| 396 | +--------------- |
| 451 | 397 | Once the device is quiesced (no more IRQs), one can call free_irq(). |
| 452 | 398 | This function will return control once any pending IRQs are handled, |
| 453 | 399 | "unhook" the drivers IRQ handler from that IRQ, and finally release |
| 454 | 400 | the IRQ if no one else is using it. |
| 455 | 401 | |
| 456 | 402 | |
| 457 | | −4.3 Stop all DMA activity |
| 458 | | −~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 403 | +Stop all DMA activity |
| 404 | +--------------------- |
| 459 | 405 | It's extremely important to stop all DMA operations BEFORE attempting |
| 460 | 406 | to deallocate DMA control data. Failure to do so can result in memory |
| 461 | 407 | corruption, hangs, and on some chip-sets a hard crash. |
| @@ -467,8 +413,8 @@ While this step sounds obvious and trivial, several "mature" drivers · 5 unmodified lines |
| 467 | 413 | didn't get this step right in the past. |
| 468 | 414 | |
| 469 | 415 | |
| 470 | | −4.4 Release DMA buffers |
| 471 | | −~~~~~~~~~~~~~~~~~~~~~~~ |
| 416 | +Release DMA buffers |
| 417 | +------------------- |
| 472 | 418 | Once DMA is stopped, clean up streaming DMA first. |
| 473 | 419 | I.e. unmap data buffers and return buffers to "upstream" |
| 474 | 420 | owners if there is one. |
| @@ -478,8 +424,8 @@ Then clean up "consistent" buffers which contain the control data. · 3 unmodified lines |
| 478 | 424 | See Documentation/DMA-API.txt for details on unmapping interfaces. |
| 479 | 425 | |
| 480 | 426 | |
| 481 | | −4.5 Unregister from other subsystems |
| 482 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 427 | +Unregister from other subsystems |
| 428 | +-------------------------------- |
| 483 | 429 | Most low level PCI device drivers support some other subsystem |
| 484 | 430 | like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your |
| 485 | 431 | driver isn't losing resources from that other subsystem. |
| @@ -487,31 +433,30 @@ If this happens, typically the symptom is an Oops (panic) when · 1 unmodified line |
| 487 | 433 | the subsystem attempts to call into a driver that has been unloaded. |
| 488 | 434 | |
| 489 | 435 | |
| 490 | | −4.6 Disable Device from responding to MMIO/IO Port addresses |
| 491 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 436 | +Disable Device from responding to MMIO/IO Port addresses |
| 437 | +-------------------------------------------------------- |
| 492 | 438 | io_unmap() MMIO or IO Port resources and then call pci_disable_device(). |
| 493 | 439 | This is the symmetric opposite of pci_enable_device(). |
| 494 | 440 | Do not access device registers after calling pci_disable_device(). |
| 495 | 441 | |
| 496 | 442 | |
| 497 | | −4.7 Release MMIO/IO Port Resource(s) |
| 498 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 443 | +Release MMIO/IO Port Resource(s) |
| 444 | +-------------------------------- |
| 499 | 445 | Call pci_release_region() to mark the MMIO or IO Port range as available. |
| 500 | 446 | Failure to do so usually results in the inability to reload the driver. |
| 501 | 447 | |
| 502 | 448 | |
| 449 | +How to access PCI config space |
| 450 | +============================== |
| 503 | 451 | |
| 504 | | −5. How to access PCI config space |
| 505 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 506 | | − |
| 507 | | −You can use pci_(read|write)_config_(byte|word|dword) to access the config |
| 508 | | −space of a device represented by struct pci_dev *. All these functions return 0 |
| 509 | | −when successful or an error code (PCIBIOS_...) which can be translated to a text |
| 510 | | −string by pcibios_strerror. Most drivers expect that accesses to valid PCI |
| 452 | +You can use `pci_(read|write)_config_(byte|word|dword)` to access the config |
| 453 | +space of a device represented by `struct pci_dev *`. All these functions return |
| 454 | +0 when successful or an error code (`PCIBIOS_...`) which can be translated to a |
| 455 | +text string by pcibios_strerror. Most drivers expect that accesses to valid PCI |
| 511 | 456 | devices don't fail. |
| 512 | 457 | |
| 513 | 458 | If you don't have a struct pci_dev available, you can call |
| 514 | | −pci_bus_(read|write)_config_(byte|word|dword) to access a given device |
| 459 | +`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device |
| 515 | 460 | and function on that bus. |
| 516 | 461 | |
| 517 | 462 | If you access fields in the standard portion of the config header, please |
| @@ -522,10 +467,10 @@ pci_find_capability() for the particular capability and it will find the · 4 unmodified lines |
| 522 | 467 | corresponding register block for you. |
| 523 | 468 | |
| 524 | 469 | |
| 470 | +Other interesting functions |
| 471 | +=========================== |
| 525 | 472 | |
| 526 | | −6. Other interesting functions |
| 527 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 528 | | − |
| 473 | +============================= ================================================ |
| 529 | 474 | pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain, |
| 530 | 475 | bus and slot and number. If the device is |
| 531 | 476 | found, its reference count is increased. |
| @@ -539,11 +484,11 @@ pci_set_drvdata() Set private driver data pointer for a pci_dev · 7 unmodified lines |
| 539 | 484 | pci_get_drvdata() Return private driver data pointer for a pci_dev |
| 540 | 485 | pci_set_mwi() Enable Memory-Write-Invalidate transactions. |
| 541 | 486 | pci_clear_mwi() Disable Memory-Write-Invalidate transactions. |
| 487 | +============================= ================================================ |
| 542 | 488 | |
| 543 | 489 | |
| 544 | | − |
| 545 | | −7. Miscellaneous hints |
| 546 | | −~~~~~~~~~~~~~~~~~~~~~~ |
| 490 | +Miscellaneous hints |
| 491 | +=================== |
| 547 | 492 | |
| 548 | 493 | When displaying PCI device names to the user (for example when a driver wants |
| 549 | 494 | to tell the user what card has it found), please use pci_name(pci_dev). |
| @@ -559,9 +504,8 @@ on the bus need to be capable of doing it, so this is something which needs · 9 unmodified lines |
| 559 | 504 | to be handled by platform and generic code, not individual drivers. |
| 560 | 505 | |
| 561 | 506 | |
| 562 | | − |
| 563 | | −8. Vendor and device identifications |
| 564 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 507 | +Vendor and device identifications |
| 508 | +================================= |
| 565 | 509 | |
| 566 | 510 | Do not add new device or vendor IDs to include/linux/pci_ids.h unless they |
| 567 | 511 | are shared across multiple drivers. You can add private definitions in |
| @@ -575,28 +519,27 @@ There are mirrors of the pci.ids file at http://pciids.sourceforge.net/ · 7 unmodified lines |
| 575 | 519 | and https://github.com/pciutils/pciids. |
| 576 | 520 | |
| 577 | 521 | |
| 578 | | − |
| 579 | | −9. Obsolete functions |
| 580 | | −~~~~~~~~~~~~~~~~~~~~~ |
| 522 | +Obsolete functions |
| 523 | +================== |
| 581 | 524 | |
| 582 | 525 | There are several functions which you might come across when trying to |
| 583 | 526 | port an old driver to the new PCI interface. They are no longer present |
| 584 | 527 | in the kernel as they aren't compatible with hotplug or PCI domains or |
| 585 | 528 | having sane locking. |
| 586 | 529 | |
| 530 | +================= =========================================== |
| 587 | 531 | pci_find_device() Superseded by pci_get_device() |
| 588 | 532 | pci_find_subsys() Superseded by pci_get_subsys() |
| 589 | 533 | pci_find_slot() Superseded by pci_get_domain_bus_and_slot() |
| 590 | 534 | pci_get_slot() Superseded by pci_get_domain_bus_and_slot() |
| 591 | | − |
| 535 | +================= =========================================== |
| 592 | 536 | |
| 593 | 537 | The alternative is the traditional PCI device driver that walks PCI |
| 594 | 538 | device lists. This is still possible but discouraged. |
| 595 | 539 | |
| 596 | 540 | |
| 597 | | − |
| 598 | | −10. MMIO Space and "Write Posting" |
| 599 | | −~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 541 | +MMIO Space and "Write Posting" |
| 542 | +============================== |
| 600 | 543 | |
| 601 | 544 | Converting a driver from using I/O Port space to using MMIO space |
| 602 | 545 | often requires some additional changes. Specifically, "write posting" |
| @@ -609,14 +552,14 @@ the CPU before the transaction has reached its destination. · 6 unmodified lines |
| 609 | 552 | |
| 610 | 553 | Thus, timing sensitive code should add readl() where the CPU is |
| 611 | 554 | expected to wait before doing other work. The classic "bit banging" |
| 612 | | −sequence works fine for I/O Port space: |
| 555 | +sequence works fine for I/O Port space:: |
| 613 | 556 | |
| 614 | 557 | for (i = 8; --i; val >>= 1) { |
| 615 | 558 | outb(val & 1, ioport_reg); /* write bit */ |
| 616 | 559 | udelay(10); |
| 617 | 560 | } |
| 618 | 561 | |
| 619 | | −The same sequence for MMIO space should be: |
| 562 | +The same sequence for MMIO space should be:: |
| 620 | 563 | |
| 621 | 564 | for (i = 8; --i; val >>= 1) { |
| 622 | 565 | writeb(val & 1, mmio_reg); /* write bit */ |
| @@ -633,4 +576,3 @@ handle the PCI master abort on all platforms if the PCI device is · 10 unmodified lines |
| 633 | 576 | expected to not respond to a readl(). Most x86 platforms will allow |
| 634 | 577 | MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage |
| 635 | 578 | (e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail"). |
| 636 | | − |