Documentation/pci.txt

   1                        Few Notes About The PCI Subsystem
   2
   3                                        or
   4
   5                 "What should you avoid when writing PCI drivers"
   6
   7           by Martin Mares <mj@atrey.karlin.mff.cuni.cz> on 13-Feb-1998
   8
   9 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  10
  11 1. How to find PCI devices
  12 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  13    In case your driver wants to search for all devices with given vendor/device
  14 ID, it should use:
  15
  16                 struct pci_dev *dev = NULL;
  17                 while (dev = pci_find_device(VENDOR_ID, DEVICE_ID, dev))
  18                         configure_device(dev);
  19
  20    For class-based search, use pci_find_class(CLASS_ID, dev).
  21
  22    In case you want to do some complex matching, look at pci_devices -- it's
  23 a linked list of pci_dev structures for all PCI devices in the system.
  24
  25    All these methods return a pointer to a pci_dev structure which is used as a
  26 parameter for many other PCI functions. The rest of them accept bus and
  27 device/function numbers which can be found in pci_dev->bus->number and
  28 pci_dev->devfn. Feel free to use all other fields of the pci_dev structure, but
  29 don't modify them.
  30
  31    The pci_present() function can be used to test presence of PCI in the
  32 machine.
  33
  34 2. How to access PCI config space
  35 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36    You can use pci_(read|write)_config_(byte|word|dword) to access the config
  37 space of a device represented by pci_dev. All these functions return 0 when
  38 successful or an error code (PCIBIOS_...) which can be translated to a text
  39 string by pcibios_strerror. Most drivers expect that accesses to valid PCI
  40 devices don't fail.
  41
  42    In case you want to address the devices by bus/device/function numbers,
  43 use pcibios_(read_write)_config_(byte|word|dword).
  44
  45    If you access fields in the standard portion of the config header, please
  46 use symbolic names of locations and bits declared in <linux/pci.h>.
  47
  48 3. Addresses and interrupts
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50    Memory and port addresses and interrupt numbers should NOT be read from the
  51 config space. You should use the values in the pci_dev structure as they might
  52 have been remapped by the kernel.
  53
  54 4. Obsolete functions
  55 ~~~~~~~~~~~~~~~~~~~~~
  56 <linux/bios32.h> is obsolete and should not be included in new code.
  57
  58 pcibios_find_(device|class) are also obsolete and should be replaced by
  59 pci_find_(device|class).
  60
  61 5. Bus mastering
  62 ~~~~~~~~~~~~~~~~
  63    If you need to setup a bus-mastering card, just call pci_set_master(). It
  64 should set PCI_COMMAND_MASTER in the command register and adjust the latency
  65 timer if needed.