lib/libpci/pci.3

   1 .\"     $NetBSD: pci.3,v 1.6 2009/03/09 19:24:27 joerg Exp $
   2 .\"
   3 .\" Copyright 2001 Wasabi Systems, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Written by Jason R. Thorpe for Wasabi Systems, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed for the NetBSD Project by
  19 .\"     Wasabi Systems, Inc.
  20 .\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
  21 .\"    or promote products derived from this software without specific prior
  22 .\"    written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
  28 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .Dd April 24, 2004
  37 .Dt PCI 3
  38 .Os
  39 .Sh NAME
  40 .Nm pci
  41 .Nd library interface for PCI bus access
  42 .Sh LIBRARY
  43 .Lb libpci
  44 .Sh SYNOPSIS
  45 .In pci.h
  46 .Ft int
  47 .Fn pcibus_conf_read "int pcifd" "u_int bus" "u_int dev" "u_int func" \
  48 "u_int reg" "pcireg_t *valp"
  49 .Ft int
  50 .Fn pcibus_conf_write "int pcifd" "u_int bus" "u_int dev" "u_int func" \
  51 "u_int reg" "pcireg_t val"
  52 .Ft int
  53 .Fn pcidev_conf_read "int devfd" "u_int reg" "pcireg_t *valp"
  54 .Ft int
  55 .Fn pcidev_conf_write "int devfd" "u_int reg" "pcireg_t val"
  56 .Ft char *
  57 .Fn pci_findvendor "pcireg_t id_reg"
  58 .Ft void
  59 .Fn pci_devinfo "pcireg_t id_reg" "pcireg_t class_reg" "char *devinfo" "size_t len"
  60 .Ft void
  61 .Fn pci_conf_print "int pcifd" "u_int bus" "u_int dev" "u_int func"
  62 .Sh DESCRIPTION
  63 The
  64 .Nm
  65 library provides support for accessing the PCI bus by user programs.
  66 .Pp
  67 These functions are available in the
  68 .Nm libpci
  69 library.
  70 Programs should be linked with
  71 .Fl lpci .
  72 .Sh CONFIGURATION SPACE FUNCTIONS
  73 The following functions are used to access PCI configuration space:
  74 .Bl -tag -width 4n
  75 .It Fn pcibus_conf_read
  76 Access the PCI configuration register
  77 .Fa reg
  78 on the device located at
  79 .Fa bus ,
  80 .Fa dev ,
  81 .Fa func ,
  82 and place the result in
  83 .Fa *valp .
  84 .Fa pcifd
  85 must be an open file descriptor to a PCI bus within the target PCI domain.
  86 .It Fn pcibus_conf_write
  87 Write the value specified by
  88 .Fa val
  89 into the PCI configuration register
  90 .Fa reg
  91 on the device located at
  92 .Fa bus ,
  93 .Fa dev ,
  94 .Fa func .
  95 .Fa pcifd
  96 must be an open file descriptor to a PCI bus within the target PCI domain.
  97 .It Fn pcidev_conf_read
  98 Access the PCI configuration register
  99 .Fa reg
 100 on the device associated with the open file descriptor
 101 .Fa devfd
 102 and place the result in
 103 .Fa *valp .
 104 .It Fn pcidev_conf_write
 105 Write the value specified by
 106 .Fa val
 107 into the PCI configuration register
 108 .Fa reg
 109 on the device associated with the open file descriptor
 110 .Fa devfd .
 111 .El
 112 .Sh MISCELLANEOUS FUNCTIONS
 113 The following miscellaneous functions are available:
 114 .Bl -tag -width 4n
 115 .It Fn pci_findvendor
 116 Return an ASCII description of the PCI vendor in the
 117 PCI ID register
 118 .Fa id_reg .
 119 .It Fn pci_devinfo
 120 Return an ASCII description of the PCI vendor, PCI product,
 121 and PCI class specified by the PCI ID register
 122 .Fa id_reg
 123 and PCI class ID register
 124 .Fa class_reg .
 125 The description is placed into the buffer pointed to by
 126 .Fa devinfo ;
 127 the size of that buffer is specified in
 128 .Fa len .
 129 .It Fn pci_conf_print
 130 Print the PCI configuration information for the device located
 131 at
 132 .Fa bus ,
 133 .Fa dev ,
 134 .Fa func .
 135 .Fa pcifd
 136 must be an open file descriptor to a PCI bus within the target PCI domain.
 137 .El
 138 .Sh RETURN VALUES
 139 The
 140 .Fn pcibus_conf_read ,
 141 .Fn pcibus_conf_write ,
 142 .Fn pcidev_conf_read ,
 143 and
 144 .Fn pcidev_conf_write
 145 functions return 0 on success and -1 on failure.
 146 .Pp
 147 The
 148 .Fn pci_findvendor
 149 function returns NULL if the PCI vendor description cannot be
 150 found.
 151 .Sh SEE ALSO
 152 .Xr pci 4
 153 .Sh HISTORY
 154 The
 155 .Fn pcibus_conf_read ,
 156 .Fn pcibus_conf_write ,
 157 .Fn pcidev_conf_read ,
 158 .Fn pcidev_conf_write ,
 159 .Fn pci_findvendor ,
 160 .Fn pci_devinfo ,
 161 and
 162 .Fn pci_conf_print
 163 functions first appeared in
 164 .Nx 1.6 .