share/man/man4/pci.4

   1 .\"
   2 .\" Copyright (c) 1999 Kenneth D. Merry.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. The name of the author may not be used to endorse or promote products
  11 .\"    derived from this software without specific prior written permission.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd January 3, 2008
  28 .Dt PCI 4
  29 .Os
  30 .Sh NAME
  31 .Nm pci
  32 .Nd generic PCI driver
  33 .Sh SYNOPSIS
  34 .Cd device pci
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 driver provides a way for userland programs to read and write
  39 .Tn PCI
  40 configuration registers.
  41 It also provides a way for userland programs to get a list of all
  42 .Tn PCI
  43 devices, or all
  44 .Tn PCI
  45 devices that match various patterns.
  46 .Pp
  47 Since the
  48 .Nm
  49 driver provides a write interface for
  50 .Tn PCI
  51 configuration registers, system administrators should exercise caution when
  52 granting access to the
  53 .Nm
  54 device.
  55 If used improperly, this driver can allow userland applications to
  56 crash a machine or cause data loss.
  57 .Pp
  58 The
  59 .Nm
  60 driver implements the
  61 .Tn PCI
  62 bus in the kernel.
  63 It enumerates any devices on the
  64 .Tn PCI
  65 bus and gives
  66 .Tn PCI
  67 client drivers the chance to attach to them.
  68 It assigns resources to children, when the BIOS does not.
  69 It takes care of routing interrupts when necessary.
  70 It reprobes the unattached
  71 .Tn PCI
  72 children when
  73 .Tn PCI
  74 client drivers are dynamically
  75 loaded at runtime.
  76 .Sh KERNEL CONFIGURATION
  77 The
  78 .Nm
  79 device is included in the kernel as described in the SYNOPSIS section.
  80 The
  81 .Nm
  82 driver cannot be built as a
  83 .Xr kld 4 .
  84 .Sh IOCTLS
  85 The following
  86 .Xr ioctl 2
  87 calls are supported by the
  88 .Nm
  89 driver.
  90 They are defined in the header file
  91 .In sys/pciio.h .
  92 .Bl -tag -width 012345678901234
  93 .It PCIOCGETCONF
  94 This
  95 .Xr ioctl 2
  96 takes a
  97 .Va pci_conf_io
  98 structure.
  99 It allows the user to retrieve information on all
 100 .Tn PCI
 101 devices in the system, or on
 102 .Tn PCI
 103 devices matching patterns supplied by the user.
 104 The call may set
 105 .Va errno
 106 to any value specified in either
 107 .Xr copyin 9
 108 or
 109 .Xr copyout 9 .
 110 The
 111 .Va pci_conf_io
 112 structure consists of a number of fields:
 113 .Bl -tag -width match_buf_len
 114 .It pat_buf_len
 115 The length, in bytes, of the buffer filled with user-supplied patterns.
 116 .It num_patterns
 117 The number of user-supplied patterns.
 118 .It patterns
 119 Pointer to a buffer filled with user-supplied patterns.
 120 .Va patterns
 121 is a pointer to
 122 .Va num_patterns
 123 .Va pci_match_conf
 124 structures.
 125 The
 126 .Va pci_match_conf
 127 structure consists of the following elements:
 128 .Bl -tag -width pd_vendor
 129 .It pc_sel
 130 .Tn PCI
 131 domain, bus, slot and function.
 132 .It pd_name
 133 .Tn PCI
 134 device driver name.
 135 .It pd_unit
 136 .Tn PCI
 137 device driver unit number.
 138 .It pc_vendor
 139 .Tn PCI
 140 vendor ID.
 141 .It pc_device
 142 .Tn PCI
 143 device ID.
 144 .It pc_class
 145 .Tn PCI
 146 device class.
 147 .It flags
 148 The flags describe which of the fields the kernel should match against.
 149 A device must match all specified fields in order to be returned.
 150 The match flags are enumerated in the
 151 .Va pci_getconf_flags
 152 structure.
 153 Hopefully the flag values are obvious enough that they do not need to
 154 described in detail.
 155 .El
 156 .It match_buf_len
 157 Length of the
 158 .Va matches
 159 buffer allocated by the user to hold the results of the
 160 .Dv PCIOCGETCONF
 161 query.
 162 .It num_matches
 163 Number of matches returned by the kernel.
 164 .It matches
 165 Buffer containing matching devices returned by the kernel.
 166 The items in this buffer are of type
 167 .Va pci_conf ,
 168 which consists of the following items:
 169 .Bl -tag -width pc_subvendor
 170 .It pc_sel
 171 .Tn PCI
 172 domain, bus, slot and function.
 173 .It pc_hdr
 174 .Tn PCI
 175 header type.
 176 .It pc_subvendor
 177 .Tn PCI
 178 subvendor ID.
 179 .It pc_subdevice
 180 .Tn PCI
 181 subdevice ID.
 182 .It pc_vendor
 183 .Tn PCI
 184 vendor ID.
 185 .It pc_device
 186 .Tn PCI
 187 device ID.
 188 .It pc_class
 189 .Tn PCI
 190 device class.
 191 .It pc_subclass
 192 .Tn PCI
 193 device subclass.
 194 .It pc_progif
 195 .Tn PCI
 196 device programming interface.
 197 .It pc_revid
 198 .Tn PCI
 199 revision ID.
 200 .It pd_name
 201 Driver name.
 202 .It pd_unit
 203 Driver unit number.
 204 .El
 205 .It offset
 206 The offset is passed in by the user to tell the kernel where it should
 207 start traversing the device list.
 208 The value passed out by the kernel
 209 points to the record immediately after the last one returned.
 210 The user may
 211 pass the value returned by the kernel in subsequent calls to the
 212 .Dv PCIOCGETCONF
 213 ioctl.
 214 If the user does not intend to use the offset, it must be set to zero.
 215 .It generation
 216 .Tn PCI
 217 configuration generation.
 218 This value only needs to be set if the offset is set.
 219 The kernel will compare the current generation number of its internal
 220 device list to the generation passed in by the user to determine whether
 221 its device list has changed since the user last called the
 222 .Dv PCIOCGETCONF
 223 ioctl.
 224 If the device list has changed, a status of
 225 .Va PCI_GETCONF_LIST_CHANGED
 226 will be passed back.
 227 .It status
 228 The status tells the user the disposition of his request for a device list.
 229 The possible status values are:
 230 .Bl -ohang
 231 .It PCI_GETCONF_LAST_DEVICE
 232 This means that there are no more devices in the PCI device list after the
 233 ones returned in the
 234 .Va matches
 235 buffer.
 236 .It PCI_GETCONF_LIST_CHANGED
 237 This status tells the user that the
 238 .Tn PCI
 239 device list has changed since his last call to the
 240 .Dv PCIOCGETCONF
 241 ioctl and he must reset the
 242 .Va offset
 243 and
 244 .Va generation
 245 to zero to start over at the beginning of the list.
 246 .It PCI_GETCONF_MORE_DEVS
 247 This tells the user that his buffer was not large enough to hold all of the
 248 remaining devices in the device list that possibly match his criteria.
 249 It is possible for this status to be returned, even when none of the remaining
 250 devices in the list would match the user's criteria.
 251 .It PCI_GETCONF_ERROR
 252 This indicates a general error while servicing the user's request.
 253 If the
 254 .Va pat_buf_len
 255 is not equal to
 256 .Va num_patterns
 257 times
 258 .Fn sizeof "struct pci_match_conf" ,
 259 .Va errno
 260 will be set to
 261 .Er EINVAL .
 262 .El
 263 .El
 264 .It PCIOCREAD
 265 This
 266 .Xr ioctl 2
 267 reads the
 268 .Tn PCI
 269 configuration registers specified by the passed-in
 270 .Va pci_io
 271 structure.
 272 The
 273 .Va pci_io
 274 structure consists of the following fields:
 275 .Bl -tag -width pi_width
 276 .It pi_sel
 277 A
 278 .Va pcisel
 279 structure which specifies the domain, bus, slot and function the user would
 280 like to query.
 281 If the specific bus is not found, errno will be set to ENODEV and -1 returned
 282 from the ioctl.
 283 .It pi_reg
 284 The
 285 .Tn PCI
 286 configuration register the user would like to access.
 287 .It pi_width
 288 The width, in bytes, of the data the user would like to read.
 289 This value
 290 may be either 1, 2, or 4.
 291 3-byte reads and reads larger than 4 bytes are
 292 not supported.
 293 If an invalid width is passed, errno will be set to EINVAL.
 294 .It pi_data
 295 The data returned by the kernel.
 296 .El
 297 .It PCIOCWRITE
 298 This
 299 .Xr ioctl 2
 300 allows users to write to the
 301 .Tn PCI
 302 specified in the passed-in
 303 .Va pci_io
 304 structure.
 305 The
 306 .Va pci_io
 307 structure is described above.
 308 The limitations on data width described for
 309 reading registers, above, also apply to writing
 310 .Tn PCI
 311 configuration registers.
 312 .El
 313 .Sh FILES
 314 .Bl -tag -width /dev/pci -compact
 315 .It Pa /dev/pci
 316 Character device for the
 317 .Nm
 318 driver.
 319 .El
 320 .Sh SEE ALSO
 321 .Xr pciconf 8
 322 .Sh HISTORY
 323 The
 324 .Nm
 325 driver (not the kernel's
 326 .Tn PCI
 327 support code) first appeared in
 328 .Fx 2.2 ,
 329 and was written by Stefan Esser and Garrett Wollman.
 330 Support for device listing and matching was re-implemented by
 331 Kenneth Merry, and first appeared in
 332 .Fx 3.0 .
 333 .Sh AUTHORS
 334 .An Kenneth Merry Aq ken@FreeBSD.org
 335 .Sh BUGS
 336 It is not possible for users to specify an accurate offset into the device
 337 list without calling the
 338 .Dv PCIOCGETCONF
 339 at least once, since they have no way of knowing the current generation
 340 number otherwise.
 341 This probably is not a serious problem, though, since
 342 users can easily narrow their search by specifying a pattern or patterns
 343 for the kernel to match against.