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
+       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.
@@ -140,34 +141,33 @@ for PCI devices manually using the following constructs:
 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):
 
-       pci_find_class(CLASS_ID, dev)
+       pci_get_class(CLASS_ID, dev)
 
 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.
 
-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
-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
@@ -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.
 
+   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
@@ -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.
-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()
-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)_*()