vserver 1.9.5.x5

[linux-2.6.git] / Documentation / pci.txt

diff --git a/Documentation/pci.txt b/Documentation/pci.txt
index d30dc10..b0676d1 100644 (file)
--- a/Documentation/pci.txt
+++ b/Documentation/pci.txt
@@ -25,6 +25,7 @@ on (either the old or the new way), it needs to perform the following steps:
        Discover resources (addresses and IRQ numbers) provided by the device
        Allocate these resources
        Communicate with the device
        Discover resources (addresses and IRQ numbers) provided by the device
        Allocate these resources
        Communicate with the device

+       Disable the device

 
 Most of these topics are covered by the following sections, for the rest
 look at <linux/pci.h>, it's hopefully well commented.
 
 Most of these topics are covered by the following sections, for the rest
 look at <linux/pci.h>, it's hopefully well commented.


@@ -140,34 +141,33 @@ for PCI devices manually using the following constructs:
 Searching by vendor and device ID:
 
        struct pci_dev *dev = NULL;
 Searching by vendor and device ID:
 
        struct pci_dev *dev = NULL;

-       while (dev = pci_find_device(VENDOR_ID, DEVICE_ID, dev))
+       while (dev = pci_get_device(VENDOR_ID, DEVICE_ID, dev))

                configure_device(dev);
 
 Searching by class ID (iterate in a similar way):
 
                configure_device(dev);
 
 Searching by class ID (iterate in a similar way):
 

-       pci_find_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_find_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).

 
    You can use the constant PCI_ANY_ID as a wildcard replacement for
 VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
 specific vendor, for example.
 
 
    You can use the constant PCI_ANY_ID as a wildcard replacement for
 VENDOR_ID or DEVICE_ID.  This allows searching for any device from a
 specific vendor, for example.
 

-Note that these functions are not hotplug-safe.  Their hotplug-safe
-replacements are pci_get_device(), pci_get_class() and pci_get_subsys().
-They increment the reference count on 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().
+   These functions are hotplug-safe. They increment the reference count on
+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().

 
 
 
 

-3. Enabling devices
-~~~~~~~~~~~~~~~~~~~
+3. Enabling and disabling devices
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    Before you do anything with the device you've found, you need to enable
 it by calling pci_enable_device() which enables I/O and memory regions of
    Before you do anything with the device you've found, you need to enable
 it by calling pci_enable_device() which enables I/O and memory regions of

-the device, assigns missing resources if needed and wakes up the device
-if it was in suspended state. Please note that this function can fail.
+the device, allocates an IRQ if necessary, assigns missing resources if
+needed and wakes up the device if it was in suspended state. Please note
+that this function can fail.

 
    If you want to use the device in bus mastering mode, call pci_set_master()
 which enables the bus master bit in PCI_COMMAND register and also fixes
 
    If you want to use the device in bus mastering mode, call pci_set_master()
 which enables the bus master bit in PCI_COMMAND register and also fixes


@@ -179,6 +179,12 @@ and also ensures that the cache line size register is set correctly.
 Make sure to check the return value of pci_set_mwi(), not all architectures
 may support Memory-Write-Invalidate.
 
 Make sure to check the return value of pci_set_mwi(), not all architectures
 may support Memory-Write-Invalidate.
 

+   If your driver decides to stop using the device (e.g., there was an
+error while setting it up or the driver module is being unloaded), it
+should call pci_disable_device() to deallocate any IRQ resources, disable
+PCI bus-mastering, etc.  You should not do anything with the device after
+calling pci_disable_device().
+

 4. How to access PCI config space
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    You can use pci_(read|write)_config_(byte|word|dword) to access the config
 4. How to access PCI config space
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    You can use pci_(read|write)_config_(byte|word|dword) to access the config


@@ -267,11 +273,12 @@ pci_present()                     of PCI subsystem when trying to talk to it.
                                devices just return NULL.
 pcibios_(read|write)_*         Superseded by their pci_(read|write)_*
                                counterparts.
                                devices just return NULL.
 pcibios_(read|write)_*         Superseded by their pci_(read|write)_*
                                counterparts.

-pcibios_find_*                 Superseded by their pci_find_* counterparts.
-pci_for_each_dev()             Superseded by pci_find_device()
+pcibios_find_*                 Superseded by their pci_get_* counterparts.
+pci_for_each_dev()             Superseded by pci_get_device()

 pci_for_each_dev_reverse()     Superseded by pci_find_device_reverse()
 pci_for_each_bus()             Superseded by pci_find_next_bus()
 pci_find_device()              Superseded by pci_get_device()
 pci_find_subsys()              Superseded by pci_get_subsys()
 pci_for_each_dev_reverse()     Superseded by pci_find_device_reverse()
 pci_for_each_bus()             Superseded by pci_find_next_bus()
 pci_find_device()              Superseded by pci_get_device()
 pci_find_subsys()              Superseded by pci_get_subsys()

-pcibios_find_class()           Superseded by pci_find_class()
+pcibios_find_class()           Superseded by pci_get_class()
+pci_find_class()               Superseded by pci_get_class()

 pci_(read|write)_*_nodev()     Superseded by pci_bus_(read|write)_*()
 pci_(read|write)_*_nodev()     Superseded by pci_bus_(read|write)_*()