Documentation: PCI: convert pci.txt to reST
Convert plain text documentation to reStructuredText format and add it to Sphinx TOC tree. No essential content change. Move the description of struct pci_driver and struct pci_device_id into in-source comments. Signed-off-by: Changbin Du <changbin.du@gmail.com> [bhelgaas: fix kernel-doc warnings related to moving descriptions to linux/pci.h, fix "space tab" whitespace errors in mod_devicetable.h] Signed-off-by: Bjorn Helgaas <bhelgaas@google.com> Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
This commit is contained in:
parent
c42eaffa16
commit
229b4e0728
@ -7,3 +7,5 @@ Linux PCI Bus Subsystem
|
|||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
:numbered:
|
:numbered:
|
||||||
|
|
||||||
|
pci
|
||||||
|
@ -1,10 +1,12 @@
|
|||||||
|
.. SPDX-License-Identifier: GPL-2.0
|
||||||
|
|
||||||
How To Write Linux PCI Drivers
|
==============================
|
||||||
|
How To Write Linux PCI Drivers
|
||||||
|
==============================
|
||||||
|
|
||||||
by Martin Mares <mj@ucw.cz> on 07-Feb-2000
|
:Authors: - Martin Mares <mj@ucw.cz>
|
||||||
updated by Grant Grundler <grundler@parisc-linux.org> on 23-Dec-2006
|
- Grant Grundler <grundler@parisc-linux.org>
|
||||||
|
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
The world of PCI is vast and full of (mostly unpleasant) surprises.
|
The world of PCI is vast and full of (mostly unpleasant) surprises.
|
||||||
Since each CPU architecture implements different chip-sets and PCI devices
|
Since each CPU architecture implements different chip-sets and PCI devices
|
||||||
have different requirements (erm, "features"), the result is the PCI support
|
have different requirements (erm, "features"), the result is the PCI support
|
||||||
@ -15,8 +17,7 @@ PCI device drivers.
|
|||||||
A more complete resource is the third edition of "Linux Device Drivers"
|
A more complete resource is the third edition of "Linux Device Drivers"
|
||||||
by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
|
by Jonathan Corbet, Alessandro Rubini, and Greg Kroah-Hartman.
|
||||||
LDD3 is available for free (under Creative Commons License) from:
|
LDD3 is available for free (under Creative Commons License) from:
|
||||||
|
http://lwn.net/Kernel/LDD3/.
|
||||||
http://lwn.net/Kernel/LDD3/
|
|
||||||
|
|
||||||
However, keep in mind that all documents are subject to "bit rot".
|
However, keep in mind that all documents are subject to "bit rot".
|
||||||
Refer to the source code if things are not working as described here.
|
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
|
|||||||
"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
|
"Linux PCI" <linux-pci@atrey.karlin.mff.cuni.cz> mailing list.
|
||||||
|
|
||||||
|
|
||||||
|
Structure of PCI drivers
|
||||||
0. Structure of PCI drivers
|
========================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
PCI drivers "discover" PCI devices in a system via pci_register_driver().
|
PCI drivers "discover" PCI devices in a system via pci_register_driver().
|
||||||
Actually, it's the other way around. When the PCI generic code discovers
|
Actually, it's the other way around. When the PCI generic code discovers
|
||||||
a new device, the driver with a matching "description" will be notified.
|
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.
|
|||||||
Once the driver knows about a PCI device and takes ownership, the
|
Once the driver knows about a PCI device and takes ownership, the
|
||||||
driver generally needs to perform the following initialization:
|
driver generally needs to perform the following initialization:
|
||||||
|
|
||||||
Enable the device
|
- Enable the device
|
||||||
Request MMIO/IOP resources
|
- Request MMIO/IOP resources
|
||||||
Set the DMA mask size (for both coherent and streaming DMA)
|
- Set the DMA mask size (for both coherent and streaming DMA)
|
||||||
Allocate and initialize shared control data (pci_allocate_coherent())
|
- Allocate and initialize shared control data (pci_allocate_coherent())
|
||||||
Access device configuration space (if needed)
|
- Access device configuration space (if needed)
|
||||||
Register IRQ handler (request_irq())
|
- Register IRQ handler (request_irq())
|
||||||
Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
||||||
Enable DMA/processing engines
|
- Enable DMA/processing engines
|
||||||
|
|
||||||
When done using the device, and perhaps the module needs to be unloaded,
|
When done using the device, and perhaps the module needs to be unloaded,
|
||||||
the driver needs to take the follow steps:
|
the driver needs to take the follow steps:
|
||||||
Disable the device from generating IRQs
|
|
||||||
Release the IRQ (free_irq())
|
- Disable the device from generating IRQs
|
||||||
Stop all DMA activity
|
- Release the IRQ (free_irq())
|
||||||
Release DMA buffers (both streaming and coherent)
|
- Stop all DMA activity
|
||||||
Unregister from other subsystems (e.g. scsi or netdev)
|
- Release DMA buffers (both streaming and coherent)
|
||||||
Release MMIO/IOP resources
|
- Unregister from other subsystems (e.g. scsi or netdev)
|
||||||
Disable the device
|
- Release MMIO/IOP resources
|
||||||
|
- Disable the device
|
||||||
|
|
||||||
Most of these topics are covered in the following sections.
|
Most of these topics are covered in the following sections.
|
||||||
For the rest look at LDD3 or <linux/pci.h> .
|
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
|
|||||||
lots of ifdefs in the drivers.
|
lots of ifdefs in the drivers.
|
||||||
|
|
||||||
|
|
||||||
|
pci_register_driver() call
|
||||||
|
==========================
|
||||||
|
|
||||||
1. pci_register_driver() call
|
PCI device drivers call ``pci_register_driver()`` during their
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
PCI device drivers call pci_register_driver() during their
|
|
||||||
initialization with a pointer to a structure describing the driver
|
initialization with a pointer to a structure describing the driver
|
||||||
(struct pci_driver):
|
(``struct pci_driver``):
|
||||||
|
|
||||||
field name Description
|
.. kernel-doc:: include/linux/pci.h
|
||||||
---------- ------------------------------------------------------
|
:functions: pci_driver
|
||||||
id_table Pointer to table of device ID's the driver is
|
|
||||||
interested in. Most drivers should export this
|
|
||||||
table using MODULE_DEVICE_TABLE(pci,...).
|
|
||||||
|
|
||||||
probe This probing function gets called (during execution
|
The ID table is an array of ``struct pci_device_id`` entries ending with an
|
||||||
of pci_register_driver() for already existing
|
|
||||||
devices or later if a new device gets inserted) for
|
|
||||||
all PCI devices which match the ID table and are not
|
|
||||||
"owned" by the other drivers yet. This function gets
|
|
||||||
passed a "struct pci_dev *" for each device whose
|
|
||||||
entry in the ID table matches the device. The probe
|
|
||||||
function returns zero when the driver chooses to
|
|
||||||
take "ownership" of the device or an error code
|
|
||||||
(negative number) otherwise.
|
|
||||||
The probe function always gets called from process
|
|
||||||
context, so it can sleep.
|
|
||||||
|
|
||||||
remove The remove() function gets called whenever a device
|
|
||||||
being handled by this driver is removed (either during
|
|
||||||
deregistration of the driver or when it's manually
|
|
||||||
pulled out of a hot-pluggable slot).
|
|
||||||
The remove function always gets called from process
|
|
||||||
context, so it can sleep.
|
|
||||||
|
|
||||||
suspend Put device into low power state.
|
|
||||||
suspend_late Put device into low power state.
|
|
||||||
|
|
||||||
resume_early Wake device from low power state.
|
|
||||||
resume Wake device from low power state.
|
|
||||||
|
|
||||||
(Please see Documentation/power/pci.txt for descriptions
|
|
||||||
of PCI Power Management and the related functions.)
|
|
||||||
|
|
||||||
shutdown Hook into reboot_notifier_list (kernel/sys.c).
|
|
||||||
Intended to stop any idling DMA operations.
|
|
||||||
Useful for enabling wake-on-lan (NIC) or changing
|
|
||||||
the power state of a device before reboot.
|
|
||||||
e.g. drivers/net/e100.c.
|
|
||||||
|
|
||||||
err_handler See Documentation/PCI/pci-error-recovery.txt
|
|
||||||
|
|
||||||
|
|
||||||
The ID table is an array of struct pci_device_id entries ending with an
|
|
||||||
all-zero entry. Definitions with static const are generally preferred.
|
all-zero entry. Definitions with static const are generally preferred.
|
||||||
|
|
||||||
Each entry consists of:
|
.. kernel-doc:: include/linux/mod_devicetable.h
|
||||||
|
:functions: pci_device_id
|
||||||
|
|
||||||
vendor,device Vendor and device ID to match (or PCI_ANY_ID)
|
Most drivers only need ``PCI_DEVICE()`` or ``PCI_DEVICE_CLASS()`` to set up
|
||||||
|
|
||||||
subvendor, Subsystem vendor and device ID to match (or PCI_ANY_ID)
|
|
||||||
subdevice,
|
|
||||||
|
|
||||||
class Device class, subclass, and "interface" to match.
|
|
||||||
See Appendix D of the PCI Local Bus Spec or
|
|
||||||
include/linux/pci_ids.h for a full list of classes.
|
|
||||||
Most drivers do not need to specify class/class_mask
|
|
||||||
as vendor/device is normally sufficient.
|
|
||||||
|
|
||||||
class_mask limit which sub-fields of the class field are compared.
|
|
||||||
See drivers/scsi/sym53c8xx_2/ for example of usage.
|
|
||||||
|
|
||||||
driver_data Data private to the driver.
|
|
||||||
Most drivers don't need to use driver_data field.
|
|
||||||
Best practice is to use driver_data as an index
|
|
||||||
into a static list of equivalent device types,
|
|
||||||
instead of using it as a pointer.
|
|
||||||
|
|
||||||
|
|
||||||
Most drivers only need PCI_DEVICE() or PCI_DEVICE_CLASS() to set up
|
|
||||||
a pci_device_id table.
|
a pci_device_id table.
|
||||||
|
|
||||||
New PCI IDs may be added to a device driver pci_ids table at runtime
|
New PCI IDs may be added to a device driver pci_ids table at runtime
|
||||||
as shown below:
|
as shown below::
|
||||||
|
|
||||||
echo "vendor device subvendor subdevice class class_mask driver_data" > \
|
echo "vendor device subvendor subdevice class class_mask driver_data" > \
|
||||||
/sys/bus/pci/drivers/{driver}/new_id
|
/sys/bus/pci/drivers/{driver}/new_id
|
||||||
|
|
||||||
All fields are passed in as hexadecimal values (no leading 0x).
|
All fields are passed in as hexadecimal values (no leading 0x).
|
||||||
The vendor and device fields are mandatory, the others are optional. Users
|
The vendor and device fields are mandatory, the others are optional. Users
|
||||||
need pass only as many optional fields as necessary:
|
need pass only as many optional fields as necessary:
|
||||||
o subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
|
|
||||||
o class and classmask fields default to 0
|
- subvendor and subdevice fields default to PCI_ANY_ID (FFFFFFFF)
|
||||||
o driver_data defaults to 0UL.
|
- class and classmask fields default to 0
|
||||||
|
- driver_data defaults to 0UL.
|
||||||
|
|
||||||
Note that driver_data must match the value used by any of the pci_device_id
|
Note that driver_data must match the value used by any of the pci_device_id
|
||||||
entries defined in the driver. This makes the driver_data field mandatory
|
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
|
|||||||
automatically calls the remove hook for all devices handled by the driver.
|
automatically calls the remove hook for all devices handled by the driver.
|
||||||
|
|
||||||
|
|
||||||
1.1 "Attributes" for driver functions/data
|
"Attributes" for driver functions/data
|
||||||
|
--------------------------------------
|
||||||
|
|
||||||
Please mark the initialization and cleanup functions where appropriate
|
Please mark the initialization and cleanup functions where appropriate
|
||||||
(the corresponding macros are defined in <linux/init.h>):
|
(the corresponding macros are defined in <linux/init.h>):
|
||||||
|
|
||||||
|
====== =================================================
|
||||||
__init Initialization code. Thrown away after the driver
|
__init Initialization code. Thrown away after the driver
|
||||||
initializes.
|
initializes.
|
||||||
__exit Exit code. Ignored for non-modular drivers.
|
__exit Exit code. Ignored for non-modular drivers.
|
||||||
|
====== =================================================
|
||||||
|
|
||||||
Tips on when/where to use the above attributes:
|
Tips on when/where to use the above attributes:
|
||||||
o The module_init()/module_exit() functions (and all
|
- The module_init()/module_exit() functions (and all
|
||||||
initialization functions called _only_ from these)
|
initialization functions called _only_ from these)
|
||||||
should be marked __init/__exit.
|
should be marked __init/__exit.
|
||||||
|
|
||||||
o Do not mark the struct pci_driver.
|
- Do not mark the struct pci_driver.
|
||||||
|
|
||||||
o Do NOT mark a function if you are not sure which mark to use.
|
- Do NOT mark a function if you are not sure which mark to use.
|
||||||
Better to not mark the function than mark the function wrong.
|
Better to not mark the function than mark the function wrong.
|
||||||
|
|
||||||
|
|
||||||
|
How to find PCI devices manually
|
||||||
2. How to find PCI devices manually
|
================================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
PCI drivers should have a really good reason for not using the
|
PCI drivers should have a really good reason for not using the
|
||||||
pci_register_driver() interface to search for PCI devices.
|
pci_register_driver() interface to search for PCI devices.
|
||||||
@ -207,17 +149,17 @@ E.g. combined serial/parallel port/floppy controller.
|
|||||||
|
|
||||||
A manual search may be performed using the following constructs:
|
A manual search may be performed using the following constructs:
|
||||||
|
|
||||||
Searching by vendor and device ID:
|
Searching by vendor and device ID::
|
||||||
|
|
||||||
struct pci_dev *dev = NULL;
|
struct pci_dev *dev = NULL;
|
||||||
while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
|
while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))
|
||||||
configure_device(dev);
|
configure_device(dev);
|
||||||
|
|
||||||
Searching by class ID (iterate in a similar way):
|
Searching by class ID (iterate in a similar way)::
|
||||||
|
|
||||||
pci_get_class(CLASS_ID, dev)
|
pci_get_class(CLASS_ID, dev)
|
||||||
|
|
||||||
Searching by both vendor/device and subsystem vendor/device ID:
|
Searching by both vendor/device and subsystem vendor/device ID::
|
||||||
|
|
||||||
pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
|
pci_get_subsys(VENDOR_ID,DEVICE_ID, SUBSYS_VENDOR_ID, SUBSYS_DEVICE_ID, dev).
|
||||||
|
|
||||||
@ -230,21 +172,20 @@ the pci_dev that they return. You must eventually (possibly at module unload)
|
|||||||
decrement the reference count on these devices by calling pci_dev_put().
|
decrement the reference count on these devices by calling pci_dev_put().
|
||||||
|
|
||||||
|
|
||||||
|
Device Initialization Steps
|
||||||
3. Device Initialization Steps
|
===========================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
As noted in the introduction, most PCI drivers need the following steps
|
As noted in the introduction, most PCI drivers need the following steps
|
||||||
for device initialization:
|
for device initialization:
|
||||||
|
|
||||||
Enable the device
|
- Enable the device
|
||||||
Request MMIO/IOP resources
|
- Request MMIO/IOP resources
|
||||||
Set the DMA mask size (for both coherent and streaming DMA)
|
- Set the DMA mask size (for both coherent and streaming DMA)
|
||||||
Allocate and initialize shared control data (pci_allocate_coherent())
|
- Allocate and initialize shared control data (pci_allocate_coherent())
|
||||||
Access device configuration space (if needed)
|
- Access device configuration space (if needed)
|
||||||
Register IRQ handler (request_irq())
|
- Register IRQ handler (request_irq())
|
||||||
Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
- Initialize non-PCI (i.e. LAN/SCSI/etc parts of the chip)
|
||||||
Enable DMA/processing engines.
|
- Enable DMA/processing engines.
|
||||||
|
|
||||||
The driver can access PCI config space registers at any time.
|
The driver can access PCI config space registers at any time.
|
||||||
(Well, almost. When running BIST, config space can go away...but
|
(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
|
|||||||
will return garbage).
|
will return garbage).
|
||||||
|
|
||||||
|
|
||||||
3.1 Enable the PCI device
|
Enable the PCI device
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------
|
||||||
Before touching any device registers, the driver needs to enable
|
Before touching any device registers, the driver needs to enable
|
||||||
the PCI device by calling pci_enable_device(). This will:
|
the PCI device by calling pci_enable_device(). This will:
|
||||||
o wake up the device if it was in suspended state,
|
|
||||||
o allocate I/O and memory regions of the device (if BIOS did not),
|
|
||||||
o allocate an IRQ (if BIOS did not).
|
|
||||||
|
|
||||||
NOTE: pci_enable_device() can fail! Check the return value.
|
- wake up the device if it was in suspended state,
|
||||||
|
- allocate I/O and memory regions of the device (if BIOS did not),
|
||||||
|
- allocate an IRQ (if BIOS did not).
|
||||||
|
|
||||||
[ OS BUG: we don't check resource allocations before enabling those
|
.. note::
|
||||||
resources. The sequence would make more sense if we called
|
pci_enable_device() can fail! Check the return value.
|
||||||
pci_request_resources() before calling pci_enable_device().
|
|
||||||
Currently, the device drivers can't detect the bug when when two
|
.. warning::
|
||||||
devices have been allocated the same range. This is not a common
|
OS BUG: we don't check resource allocations before enabling those
|
||||||
problem and unlikely to get fixed soon.
|
resources. The sequence would make more sense if we called
|
||||||
|
pci_request_resources() before calling pci_enable_device().
|
||||||
|
Currently, the device drivers can't detect the bug when when two
|
||||||
|
devices have been allocated the same range. This is not a common
|
||||||
|
problem and unlikely to get fixed soon.
|
||||||
|
|
||||||
|
This has been discussed before but not changed as of 2.6.19:
|
||||||
|
http://lkml.org/lkml/2006/3/2/194
|
||||||
|
|
||||||
This has been discussed before but not changed as of 2.6.19:
|
|
||||||
http://lkml.org/lkml/2006/3/2/194
|
|
||||||
]
|
|
||||||
|
|
||||||
pci_set_master() will enable DMA by setting the bus master bit
|
pci_set_master() will enable DMA by setting the bus master bit
|
||||||
in the PCI_COMMAND register. It also fixes the latency timer value if
|
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
|
|||||||
Mem-Wr-Inval.
|
Mem-Wr-Inval.
|
||||||
|
|
||||||
|
|
||||||
3.2 Request MMIO/IOP resources
|
Request MMIO/IOP resources
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------------
|
||||||
Memory (MMIO), and I/O port addresses should NOT be read directly
|
Memory (MMIO), and I/O port addresses should NOT be read directly
|
||||||
from the PCI device config space. Use the values in the pci_dev structure
|
from the PCI device config space. Use the values in the pci_dev structure
|
||||||
as the PCI "bus address" might have been remapped to a "host physical"
|
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
|
|||||||
calling pci_disable_device().
|
calling pci_disable_device().
|
||||||
The idea is to prevent two devices colliding on the same address range.
|
The idea is to prevent two devices colliding on the same address range.
|
||||||
|
|
||||||
[ See OS BUG comment above. Currently (2.6.19), The driver can only
|
.. tip::
|
||||||
determine MMIO and IO Port resource availability _after_ calling
|
See OS BUG comment above. Currently (2.6.19), The driver can only
|
||||||
pci_enable_device(). ]
|
determine MMIO and IO Port resource availability _after_ calling
|
||||||
|
pci_enable_device().
|
||||||
|
|
||||||
Generic flavors of pci_request_region() are request_mem_region()
|
Generic flavors of pci_request_region() are request_mem_region()
|
||||||
(for MMIO ranges) and request_region() (for IO Port ranges).
|
(for MMIO ranges) and request_region() (for IO Port ranges).
|
||||||
@ -316,12 +261,13 @@ BARs.
|
|||||||
Also see pci_request_selected_regions() below.
|
Also see pci_request_selected_regions() below.
|
||||||
|
|
||||||
|
|
||||||
3.3 Set the DMA mask size
|
Set the DMA mask size
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------
|
||||||
[ If anything below doesn't make sense, please refer to
|
.. note::
|
||||||
Documentation/DMA-API.txt. This section is just a reminder that
|
If anything below doesn't make sense, please refer to
|
||||||
drivers need to indicate DMA capabilities of the device and is not
|
Documentation/DMA-API.txt. This section is just a reminder that
|
||||||
an authoritative source for DMA interfaces. ]
|
drivers need to indicate DMA capabilities of the device and is not
|
||||||
|
an authoritative source for DMA interfaces.
|
||||||
|
|
||||||
While all drivers should explicitly indicate the DMA capability
|
While all drivers should explicitly indicate the DMA capability
|
||||||
(e.g. 32 or 64 bit) of the PCI bus master, devices with more than
|
(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
|
|||||||
("consistent") data.
|
("consistent") data.
|
||||||
|
|
||||||
|
|
||||||
3.4 Setup shared control data
|
Setup shared control data
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
-------------------------
|
||||||
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
|
Once the DMA masks are set, the driver can allocate "consistent" (a.k.a. shared)
|
||||||
memory. See Documentation/DMA-API.txt for a full description of
|
memory. See Documentation/DMA-API.txt for a full description of
|
||||||
the DMA APIs. This section is just a reminder that it needs to be done
|
the DMA APIs. This section is just a reminder that it needs to be done
|
||||||
before enabling DMA on the device.
|
before enabling DMA on the device.
|
||||||
|
|
||||||
|
|
||||||
3.5 Initialize device registers
|
Initialize device registers
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------------
|
||||||
Some drivers will need specific "capability" fields programmed
|
Some drivers will need specific "capability" fields programmed
|
||||||
or other "vendor specific" register initialized or reset.
|
or other "vendor specific" register initialized or reset.
|
||||||
E.g. clearing pending interrupts.
|
E.g. clearing pending interrupts.
|
||||||
|
|
||||||
|
|
||||||
3.6 Register IRQ handler
|
Register IRQ handler
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------
|
||||||
While calling request_irq() is the last step described here,
|
While calling request_irq() is the last step described here,
|
||||||
this is often just another intermediate step to initialize a device.
|
this is often just another intermediate step to initialize a device.
|
||||||
This step can often be deferred until the device is opened for use.
|
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
|
|||||||
pci_alloc_irq_vectors.
|
pci_alloc_irq_vectors.
|
||||||
|
|
||||||
There are (at least) two really good reasons for using MSI:
|
There are (at least) two really good reasons for using MSI:
|
||||||
|
|
||||||
1) MSI is an exclusive interrupt vector by definition.
|
1) MSI is an exclusive interrupt vector by definition.
|
||||||
This means the interrupt handler doesn't have to verify
|
This means the interrupt handler doesn't have to verify
|
||||||
its device caused the interrupt.
|
its device caused the interrupt.
|
||||||
@ -410,24 +357,23 @@ See drivers/infiniband/hw/mthca/ or drivers/net/tg3.c for examples
|
|||||||
of MSI/MSI-X usage.
|
of MSI/MSI-X usage.
|
||||||
|
|
||||||
|
|
||||||
|
PCI device shutdown
|
||||||
4. PCI device shutdown
|
===================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
When a PCI device driver is being unloaded, most of the following
|
When a PCI device driver is being unloaded, most of the following
|
||||||
steps need to be performed:
|
steps need to be performed:
|
||||||
|
|
||||||
Disable the device from generating IRQs
|
- Disable the device from generating IRQs
|
||||||
Release the IRQ (free_irq())
|
- Release the IRQ (free_irq())
|
||||||
Stop all DMA activity
|
- Stop all DMA activity
|
||||||
Release DMA buffers (both streaming and consistent)
|
- Release DMA buffers (both streaming and consistent)
|
||||||
Unregister from other subsystems (e.g. scsi or netdev)
|
- Unregister from other subsystems (e.g. scsi or netdev)
|
||||||
Disable device from responding to MMIO/IO Port addresses
|
- Disable device from responding to MMIO/IO Port addresses
|
||||||
Release MMIO/IO Port resource(s)
|
- Release MMIO/IO Port resource(s)
|
||||||
|
|
||||||
|
|
||||||
4.1 Stop IRQs on the device
|
Stop IRQs on the device
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
-----------------------
|
||||||
How to do this is chip/device specific. If it's not done, it opens
|
How to do this is chip/device specific. If it's not done, it opens
|
||||||
the possibility of a "screaming interrupt" if (and only if)
|
the possibility of a "screaming interrupt" if (and only if)
|
||||||
the IRQ is shared with another device.
|
the IRQ is shared with another device.
|
||||||
@ -446,16 +392,16 @@ MSI and MSI-X are defined to be exclusive interrupts and thus
|
|||||||
are not susceptible to the "screaming interrupt" problem.
|
are not susceptible to the "screaming interrupt" problem.
|
||||||
|
|
||||||
|
|
||||||
4.2 Release the IRQ
|
Release the IRQ
|
||||||
~~~~~~~~~~~~~~~~~~~
|
---------------
|
||||||
Once the device is quiesced (no more IRQs), one can call free_irq().
|
Once the device is quiesced (no more IRQs), one can call free_irq().
|
||||||
This function will return control once any pending IRQs are handled,
|
This function will return control once any pending IRQs are handled,
|
||||||
"unhook" the drivers IRQ handler from that IRQ, and finally release
|
"unhook" the drivers IRQ handler from that IRQ, and finally release
|
||||||
the IRQ if no one else is using it.
|
the IRQ if no one else is using it.
|
||||||
|
|
||||||
|
|
||||||
4.3 Stop all DMA activity
|
Stop all DMA activity
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
---------------------
|
||||||
It's extremely important to stop all DMA operations BEFORE attempting
|
It's extremely important to stop all DMA operations BEFORE attempting
|
||||||
to deallocate DMA control data. Failure to do so can result in memory
|
to deallocate DMA control data. Failure to do so can result in memory
|
||||||
corruption, hangs, and on some chip-sets a hard crash.
|
corruption, hangs, and on some chip-sets a hard crash.
|
||||||
@ -467,8 +413,8 @@ While this step sounds obvious and trivial, several "mature" drivers
|
|||||||
didn't get this step right in the past.
|
didn't get this step right in the past.
|
||||||
|
|
||||||
|
|
||||||
4.4 Release DMA buffers
|
Release DMA buffers
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~
|
-------------------
|
||||||
Once DMA is stopped, clean up streaming DMA first.
|
Once DMA is stopped, clean up streaming DMA first.
|
||||||
I.e. unmap data buffers and return buffers to "upstream"
|
I.e. unmap data buffers and return buffers to "upstream"
|
||||||
owners if there is one.
|
owners if there is one.
|
||||||
@ -478,8 +424,8 @@ Then clean up "consistent" buffers which contain the control data.
|
|||||||
See Documentation/DMA-API.txt for details on unmapping interfaces.
|
See Documentation/DMA-API.txt for details on unmapping interfaces.
|
||||||
|
|
||||||
|
|
||||||
4.5 Unregister from other subsystems
|
Unregister from other subsystems
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------------------
|
||||||
Most low level PCI device drivers support some other subsystem
|
Most low level PCI device drivers support some other subsystem
|
||||||
like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
|
like USB, ALSA, SCSI, NetDev, Infiniband, etc. Make sure your
|
||||||
driver isn't losing resources from that other subsystem.
|
driver isn't losing resources from that other subsystem.
|
||||||
@ -487,31 +433,30 @@ If this happens, typically the symptom is an Oops (panic) when
|
|||||||
the subsystem attempts to call into a driver that has been unloaded.
|
the subsystem attempts to call into a driver that has been unloaded.
|
||||||
|
|
||||||
|
|
||||||
4.6 Disable Device from responding to MMIO/IO Port addresses
|
Disable Device from responding to MMIO/IO Port addresses
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------------------------------------------
|
||||||
io_unmap() MMIO or IO Port resources and then call pci_disable_device().
|
io_unmap() MMIO or IO Port resources and then call pci_disable_device().
|
||||||
This is the symmetric opposite of pci_enable_device().
|
This is the symmetric opposite of pci_enable_device().
|
||||||
Do not access device registers after calling pci_disable_device().
|
Do not access device registers after calling pci_disable_device().
|
||||||
|
|
||||||
|
|
||||||
4.7 Release MMIO/IO Port Resource(s)
|
Release MMIO/IO Port Resource(s)
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
--------------------------------
|
||||||
Call pci_release_region() to mark the MMIO or IO Port range as available.
|
Call pci_release_region() to mark the MMIO or IO Port range as available.
|
||||||
Failure to do so usually results in the inability to reload the driver.
|
Failure to do so usually results in the inability to reload the driver.
|
||||||
|
|
||||||
|
|
||||||
|
How to access PCI config space
|
||||||
|
==============================
|
||||||
|
|
||||||
5. How to access PCI config space
|
You can use `pci_(read|write)_config_(byte|word|dword)` to access the config
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
space of a device represented by `struct pci_dev *`. All these functions return
|
||||||
|
0 when successful or an error code (`PCIBIOS_...`) which can be translated to a
|
||||||
You can use pci_(read|write)_config_(byte|word|dword) to access the config
|
text string by pcibios_strerror. Most drivers expect that accesses to valid PCI
|
||||||
space of a device represented by struct pci_dev *. All these functions return 0
|
|
||||||
when successful or an error code (PCIBIOS_...) which can be translated to a text
|
|
||||||
string by pcibios_strerror. Most drivers expect that accesses to valid PCI
|
|
||||||
devices don't fail.
|
devices don't fail.
|
||||||
|
|
||||||
If you don't have a struct pci_dev available, you can call
|
If you don't have a struct pci_dev available, you can call
|
||||||
pci_bus_(read|write)_config_(byte|word|dword) to access a given device
|
`pci_bus_(read|write)_config_(byte|word|dword)` to access a given device
|
||||||
and function on that bus.
|
and function on that bus.
|
||||||
|
|
||||||
If you access fields in the standard portion of the config header, please
|
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
|
|||||||
corresponding register block for you.
|
corresponding register block for you.
|
||||||
|
|
||||||
|
|
||||||
|
Other interesting functions
|
||||||
|
===========================
|
||||||
|
|
||||||
6. Other interesting functions
|
============================= ================================================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
|
pci_get_domain_bus_and_slot() Find pci_dev corresponding to given domain,
|
||||||
bus and slot and number. If the device is
|
bus and slot and number. If the device is
|
||||||
found, its reference count is increased.
|
found, its reference count is increased.
|
||||||
@ -539,11 +484,11 @@ pci_set_drvdata() Set private driver data pointer for a pci_dev
|
|||||||
pci_get_drvdata() Return private driver data pointer for a pci_dev
|
pci_get_drvdata() Return private driver data pointer for a pci_dev
|
||||||
pci_set_mwi() Enable Memory-Write-Invalidate transactions.
|
pci_set_mwi() Enable Memory-Write-Invalidate transactions.
|
||||||
pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
|
pci_clear_mwi() Disable Memory-Write-Invalidate transactions.
|
||||||
|
============================= ================================================
|
||||||
|
|
||||||
|
|
||||||
|
Miscellaneous hints
|
||||||
7. Miscellaneous hints
|
===================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
When displaying PCI device names to the user (for example when a driver wants
|
When displaying PCI device names to the user (for example when a driver wants
|
||||||
to tell the user what card has it found), please use pci_name(pci_dev).
|
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
|
|||||||
to be handled by platform and generic code, not individual drivers.
|
to be handled by platform and generic code, not individual drivers.
|
||||||
|
|
||||||
|
|
||||||
|
Vendor and device identifications
|
||||||
8. Vendor and device identifications
|
=================================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
|
Do not add new device or vendor IDs to include/linux/pci_ids.h unless they
|
||||||
are shared across multiple drivers. You can add private definitions in
|
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/
|
|||||||
and https://github.com/pciutils/pciids.
|
and https://github.com/pciutils/pciids.
|
||||||
|
|
||||||
|
|
||||||
|
Obsolete functions
|
||||||
9. Obsolete functions
|
==================
|
||||||
~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
There are several functions which you might come across when trying to
|
There are several functions which you might come across when trying to
|
||||||
port an old driver to the new PCI interface. They are no longer present
|
port an old driver to the new PCI interface. They are no longer present
|
||||||
in the kernel as they aren't compatible with hotplug or PCI domains or
|
in the kernel as they aren't compatible with hotplug or PCI domains or
|
||||||
having sane locking.
|
having sane locking.
|
||||||
|
|
||||||
|
================= ===========================================
|
||||||
pci_find_device() Superseded by pci_get_device()
|
pci_find_device() Superseded by pci_get_device()
|
||||||
pci_find_subsys() Superseded by pci_get_subsys()
|
pci_find_subsys() Superseded by pci_get_subsys()
|
||||||
pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
|
pci_find_slot() Superseded by pci_get_domain_bus_and_slot()
|
||||||
pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
|
pci_get_slot() Superseded by pci_get_domain_bus_and_slot()
|
||||||
|
================= ===========================================
|
||||||
|
|
||||||
The alternative is the traditional PCI device driver that walks PCI
|
The alternative is the traditional PCI device driver that walks PCI
|
||||||
device lists. This is still possible but discouraged.
|
device lists. This is still possible but discouraged.
|
||||||
|
|
||||||
|
|
||||||
|
MMIO Space and "Write Posting"
|
||||||
10. MMIO Space and "Write Posting"
|
==============================
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
||||||
|
|
||||||
Converting a driver from using I/O Port space to using MMIO space
|
Converting a driver from using I/O Port space to using MMIO space
|
||||||
often requires some additional changes. Specifically, "write posting"
|
often requires some additional changes. Specifically, "write posting"
|
||||||
@ -609,14 +552,14 @@ the CPU before the transaction has reached its destination.
|
|||||||
|
|
||||||
Thus, timing sensitive code should add readl() where the CPU is
|
Thus, timing sensitive code should add readl() where the CPU is
|
||||||
expected to wait before doing other work. The classic "bit banging"
|
expected to wait before doing other work. The classic "bit banging"
|
||||||
sequence works fine for I/O Port space:
|
sequence works fine for I/O Port space::
|
||||||
|
|
||||||
for (i = 8; --i; val >>= 1) {
|
for (i = 8; --i; val >>= 1) {
|
||||||
outb(val & 1, ioport_reg); /* write bit */
|
outb(val & 1, ioport_reg); /* write bit */
|
||||||
udelay(10);
|
udelay(10);
|
||||||
}
|
}
|
||||||
|
|
||||||
The same sequence for MMIO space should be:
|
The same sequence for MMIO space should be::
|
||||||
|
|
||||||
for (i = 8; --i; val >>= 1) {
|
for (i = 8; --i; val >>= 1) {
|
||||||
writeb(val & 1, mmio_reg); /* write bit */
|
writeb(val & 1, mmio_reg); /* write bit */
|
||||||
@ -633,4 +576,3 @@ handle the PCI master abort on all platforms if the PCI device is
|
|||||||
expected to not respond to a readl(). Most x86 platforms will allow
|
expected to not respond to a readl(). Most x86 platforms will allow
|
||||||
MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
|
MMIO reads to master abort (a.k.a. "Soft Fail") and return garbage
|
||||||
(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
|
(e.g. ~0). But many RISC platforms will crash (a.k.a."Hard Fail").
|
||||||
|
|
@ -16,6 +16,25 @@ typedef unsigned long kernel_ulong_t;
|
|||||||
|
|
||||||
#define PCI_ANY_ID (~0)
|
#define PCI_ANY_ID (~0)
|
||||||
|
|
||||||
|
/**
|
||||||
|
* struct pci_device_id - PCI device ID structure
|
||||||
|
* @vendor: Vendor ID to match (or PCI_ANY_ID)
|
||||||
|
* @device: Device ID to match (or PCI_ANY_ID)
|
||||||
|
* @subvendor: Subsystem vendor ID to match (or PCI_ANY_ID)
|
||||||
|
* @subdevice: Subsystem device ID to match (or PCI_ANY_ID)
|
||||||
|
* @class: Device class, subclass, and "interface" to match.
|
||||||
|
* See Appendix D of the PCI Local Bus Spec or
|
||||||
|
* include/linux/pci_ids.h for a full list of classes.
|
||||||
|
* Most drivers do not need to specify class/class_mask
|
||||||
|
* as vendor/device is normally sufficient.
|
||||||
|
* @class_mask: Limit which sub-fields of the class field are compared.
|
||||||
|
* See drivers/scsi/sym53c8xx_2/ for example of usage.
|
||||||
|
* @driver_data: Data private to the driver.
|
||||||
|
* Most drivers don't need to use driver_data field.
|
||||||
|
* Best practice is to use driver_data as an index
|
||||||
|
* into a static list of equivalent device types,
|
||||||
|
* instead of using it as a pointer.
|
||||||
|
*/
|
||||||
struct pci_device_id {
|
struct pci_device_id {
|
||||||
__u32 vendor, device; /* Vendor and device ID or PCI_ANY_ID*/
|
__u32 vendor, device; /* Vendor and device ID or PCI_ANY_ID*/
|
||||||
__u32 subvendor, subdevice; /* Subsystem ID's or PCI_ANY_ID */
|
__u32 subvendor, subdevice; /* Subsystem ID's or PCI_ANY_ID */
|
||||||
@ -257,17 +276,17 @@ struct pcmcia_device_id {
|
|||||||
__u16 match_flags;
|
__u16 match_flags;
|
||||||
|
|
||||||
__u16 manf_id;
|
__u16 manf_id;
|
||||||
__u16 card_id;
|
__u16 card_id;
|
||||||
|
|
||||||
__u8 func_id;
|
__u8 func_id;
|
||||||
|
|
||||||
/* for real multi-function devices */
|
/* for real multi-function devices */
|
||||||
__u8 function;
|
__u8 function;
|
||||||
|
|
||||||
/* for pseudo multi-function devices */
|
/* for pseudo multi-function devices */
|
||||||
__u8 device_no;
|
__u8 device_no;
|
||||||
|
|
||||||
__u32 prod_id_hash[4];
|
__u32 prod_id_hash[4];
|
||||||
|
|
||||||
/* not matched against in kernelspace */
|
/* not matched against in kernelspace */
|
||||||
const char * prod_id[4];
|
const char * prod_id[4];
|
||||||
|
@ -151,6 +151,8 @@ static inline const char *pci_power_name(pci_power_t state)
|
|||||||
#define PCI_PM_BUS_WAIT 50
|
#define PCI_PM_BUS_WAIT 50
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
* typedef pci_channel_state_t
|
||||||
|
*
|
||||||
* The pci_channel state describes connectivity between the CPU and
|
* The pci_channel state describes connectivity between the CPU and
|
||||||
* the PCI device. If some PCI bus between here and the PCI device
|
* the PCI device. If some PCI bus between here and the PCI device
|
||||||
* has crashed or locked up, this info is reflected here.
|
* has crashed or locked up, this info is reflected here.
|
||||||
@ -775,6 +777,50 @@ struct pci_error_handlers {
|
|||||||
|
|
||||||
|
|
||||||
struct module;
|
struct module;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* struct pci_driver - PCI driver structure
|
||||||
|
* @node: List of driver structures.
|
||||||
|
* @name: Driver name.
|
||||||
|
* @id_table: Pointer to table of device IDs the driver is
|
||||||
|
* interested in. Most drivers should export this
|
||||||
|
* table using MODULE_DEVICE_TABLE(pci,...).
|
||||||
|
* @probe: This probing function gets called (during execution
|
||||||
|
* of pci_register_driver() for already existing
|
||||||
|
* devices or later if a new device gets inserted) for
|
||||||
|
* all PCI devices which match the ID table and are not
|
||||||
|
* "owned" by the other drivers yet. This function gets
|
||||||
|
* passed a "struct pci_dev \*" for each device whose
|
||||||
|
* entry in the ID table matches the device. The probe
|
||||||
|
* function returns zero when the driver chooses to
|
||||||
|
* take "ownership" of the device or an error code
|
||||||
|
* (negative number) otherwise.
|
||||||
|
* The probe function always gets called from process
|
||||||
|
* context, so it can sleep.
|
||||||
|
* @remove: The remove() function gets called whenever a device
|
||||||
|
* being handled by this driver is removed (either during
|
||||||
|
* deregistration of the driver or when it's manually
|
||||||
|
* pulled out of a hot-pluggable slot).
|
||||||
|
* The remove function always gets called from process
|
||||||
|
* context, so it can sleep.
|
||||||
|
* @suspend: Put device into low power state.
|
||||||
|
* @suspend_late: Put device into low power state.
|
||||||
|
* @resume_early: Wake device from low power state.
|
||||||
|
* @resume: Wake device from low power state.
|
||||||
|
* (Please see Documentation/power/pci.txt for descriptions
|
||||||
|
* of PCI Power Management and the related functions.)
|
||||||
|
* @shutdown: Hook into reboot_notifier_list (kernel/sys.c).
|
||||||
|
* Intended to stop any idling DMA operations.
|
||||||
|
* Useful for enabling wake-on-lan (NIC) or changing
|
||||||
|
* the power state of a device before reboot.
|
||||||
|
* e.g. drivers/net/e100.c.
|
||||||
|
* @sriov_configure: Optional driver callback to allow configuration of
|
||||||
|
* number of VFs to enable via sysfs "sriov_numvfs" file.
|
||||||
|
* @err_handler: See Documentation/PCI/pci-error-recovery.rst
|
||||||
|
* @groups: Sysfs attribute groups.
|
||||||
|
* @driver: Driver model structure.
|
||||||
|
* @dynids: List of dynamically added device IDs.
|
||||||
|
*/
|
||||||
struct pci_driver {
|
struct pci_driver {
|
||||||
struct list_head node;
|
struct list_head node;
|
||||||
const char *name;
|
const char *name;
|
||||||
@ -2206,7 +2252,7 @@ static inline u8 pci_vpd_srdt_tag(const u8 *srdt)
|
|||||||
|
|
||||||
/**
|
/**
|
||||||
* pci_vpd_info_field_size - Extracts the information field length
|
* pci_vpd_info_field_size - Extracts the information field length
|
||||||
* @lrdt: Pointer to the beginning of an information field header
|
* @info_field: Pointer to the beginning of an information field header
|
||||||
*
|
*
|
||||||
* Returns the extracted information field length.
|
* Returns the extracted information field length.
|
||||||
*/
|
*/
|
||||||
|
Loading…
Reference in New Issue
Block a user