FreeBSD 7.0 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

pci - generic PCI driver

 

NAME

      pci - generic PCI driver
 

SYNOPSIS

      device pci
 

DESCRIPTION

      The pci driver provides a way for userland programs to read and write PCI
      configuration registers.  It also provides a way for userland programs to
      get a list of all PCI devices, or all PCI devices that match various pat‐
      terns.
 
      Since the pci driver provides a write interface for PCI configuration
      registers, system administrators should exercise caution when granting
      access to the pci device.  If used improperly, this driver can allow
      userland applications to crash a machine or cause data loss.
      It is only necessary to specify one pci controller in the kernel.  Addi‐
      tional PCI busses are handled automatically as they are encountered.
 

IOCTLS

      The following ioctl(2) calls are supported by the pci driver.  They are
      defined in the header file
 
      PCIOCGETCONF     This ioctl(2) takes a pci_conf_io structure.  It allows
                       the user to retrieve information on all PCI devices in
                       the system, or on PCI devices matching patterns supplied
                       by the user.  The call may set errno to any value speci‐
                       fied in either copyin(9) or copyout(9).  The pci_conf_io
                       structure consists of a number of fields:
 
                       pat_buf_len    The length, in bytes, of the buffer
                                      filled with user-supplied patterns.
 
                       num_patterns   The number of user-supplied patterns.
 
                       patterns       Pointer to a buffer filled with user-sup‐
                                      plied patterns.  patterns is a pointer to
                                      num_patterns pci_match_conf structures.
                                      The pci_match_conf structure consists of
                                      the following elements:
 
                                      pc_sel     PCI domain, bus, slot and
                                                 function.
 
                                      pd_name    PCI device driver name.
 
                                      pd_unit    PCI device driver unit number.
 
                                      pc_vendor  PCI vendor ID.
 
                                      pc_device  PCI device ID.
 
                                      pc_class   PCI device class.
 
                                      flags      The flags describe which of
                                                 the fields the kernel should
                                                 match against.  A device must
                                                 match all specified fields in
                                                 order to be returned.  The
                                                 match flags are enumerated in
                                                 the pci_getconf_flags struc‐
                                                 ture.  Hopefully the flag val‐
                                                 ues are obvious enough that
                                                 they do not need to described
                                                 in detail.
 
                       match_buf_len  Length of the matches buffer allocated by
                                      the user to hold the results of the
                                      PCIOCGETCONF query.
 
                       num_matches    Number of matches returned by the kernel.
 
                       matches        Buffer containing matching devices
                                      returned by the kernel.  The items in
                                      this buffer are of type pci_conf, which
                                      consists of the following items:
 
                                      pc_sel        PCI domain, bus, slot and
                                                    function.
 
                                      pc_hdr        PCI header type.
 
                                      pc_subvendor  PCI subvendor ID.
 
                                      pc_subdevice  PCI subdevice ID.
 
                                      pc_vendor     PCI vendor ID.
 
                                      pc_device     PCI device ID.
 
                                      pc_class      PCI device class.
 
                                      pc_subclass   PCI device subclass.
 
                                      pc_progif     PCI device programming
                                                    interface.
 
                                      pc_revid      PCI revision ID.
 
                                      pd_name       Driver name.
 
                                      pd_unit       Driver unit number.
 
                       offset         The offset is passed in by the user to
                                      tell the kernel where it should start
                                      traversing the device list.  The value
                                      passed out by the kernel points to the
                                      record immediately after the last one
                                      returned.  The user may pass the value
                                      returned by the kernel in subsequent
                                      calls to the PCIOCGETCONF ioctl.  If the
                                      user does not intend to use the offset,
                                      it must be set to zero.
 
                       generation     PCI configuration generation.  This value
                                      only needs to be set if the offset is
                                      set.  The kernel will compare the current
                                      generation number of its internal device
                                      list to the generation passed in by the
                                      user to determine whether its device list
                                      has changed since the user last called
                                      the PCIOCGETCONF ioctl.  If the device
                                      list has changed, a status of
                                      PCI_GETCONF_LIST_CHANGED will be passed
                                      back.
 
                       status         The status tells the user the disposition
                                      of his request for a device list.  The
                                      possible status values are:
 
                                      PCI_GETCONF_LAST_DEVICE
                                      This means that there are no more devices
                                      in the PCI device list after the ones
                                      returned in the matches buffer.
 
                                      PCI_GETCONF_LIST_CHANGED
                                      This status tells the user that the PCI
                                      device list has changed since his last
                                      call to the PCIOCGETCONF ioctl and he
                                      must reset the offset and generation to
                                      zero to start over at the beginning of
                                      the list.
 
                                      PCI_GETCONF_MORE_DEVS
                                      This tells the user that his buffer was
                                      not large enough to hold all of the
                                      remaining devices in the device list that
                                      possibly match his criteria.  It is pos‐
                                      sible for this status to be returned,
                                      even when none of the remaining devices
                                      in the list would match the user’s crite‐
                                      ria.
 
                                      PCI_GETCONF_ERROR
                                      This indicates a general error while ser‐
                                      vicing the user’s request.  If the
                                      pat_buf_len is not equal to num_patterns
                                      times sizeof(struct pci_match_conf),
                                      errno will be set to EINVAL.
 
      PCIOCREAD        This ioctl(2) reads the PCI configuration registers
                       specified by the passed-in pci_io structure.  The pci_io
                       structure consists of the following fields:
 
                       pi_sel    A pcisel structure which specifies the domain,
                                 bus, slot and function the user would like to
                                 query.  If the specific bus is not found,
                                 errno will be set to ENODEV and -1 returned
                                 from the ioctl.
 
                       pi_reg    The PCI configuration register the user would
                                 like to access.
 
                       pi_width  The width, in bytes, of the data the user
                                 would like to read.  This value may be either
                                 1, 2, or 4.  3-byte reads and reads larger
                                 than 4 bytes are not supported.  If an invalid
                                 width is passed, errno will be set to EINVAL.
 
                       pi_data   The data returned by the kernel.
 
      PCIOCWRITE       This ioctl(2) allows users to write to the PCI specified
                       in the passed-in pci_io structure.  The pci_io structure
                       is described above.  The limitations on data width
                       described for reading registers, above, also apply to
                       writing PCI configuration registers.
 

FILES

      /dev/pci  Character device for the pci driver.
      pciconf(8)
 

HISTORY

      The pci driver (not the kernel’s PCI support code) first appeared in
      FreeBSD 2.2, and was written by Stefan Esser and Garrett Wollman.  Sup‐
      port for device listing and matching was re-implemented by Kenneth Merry,
      and first appeared in FreeBSD 3.0.
 

AUTHORS

      Kenneth Merry 〈ken@FreeBSD.org〉
 

BUGS

      It is not possible for users to specify an accurate offset into the
      device list without calling the PCIOCGETCONF at least once, since they
      have no way of knowing the current generation number otherwise.  This
      probably is not a serious problem, though, since users can easily narrow
      their search by specifying a pattern or patterns for the kernel to match
      against.
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.