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 .Pp
  94 .It PCIOCGETCONF
  95 This
  96 .Xr ioctl 2
  97 takes a
  98 .Va pci_conf_io
  99 structure.
 100 It allows the user to retrieve information on all
 101 .Tn PCI
 102 devices in the system, or on
 103 .Tn PCI
 104 devices matching patterns supplied by the user.
 105 The call may set
 106 .Va errno
 107 to any value specified in either
 108 .Xr copyin 9
 109 or
 110 .Xr copyout 9 .
 111 The
 112 .Va pci_conf_io
 113 structure consists of a number of fields:
 114 .Bl -tag -width match_buf_len
 115 .It pat_buf_len
 116 The length, in bytes, of the buffer filled with user-supplied patterns.
 117 .It num_patterns
 118 The number of user-supplied patterns.
 119 .It patterns
 120 Pointer to a buffer filled with user-supplied patterns.
 121 .Va patterns
 122 is a pointer to
 123 .Va num_patterns
 124 .Va pci_match_conf
 125 structures.
 126 The
 127 .Va pci_match_conf
 128 structure consists of the following elements:
 129 .Bl -tag -width pd_vendor
 130 .It pc_sel
 131 .Tn PCI
 132 domain, bus, slot and function.
 133 .It pd_name
 134 .Tn PCI
 135 device driver name.
 136 .It pd_unit
 137 .Tn PCI
 138 device driver unit number.
 139 .It pc_vendor
 140 .Tn PCI
 141 vendor ID.
 142 .It pc_device
 143 .Tn PCI
 144 device ID.
 145 .It pc_class
 146 .Tn PCI
 147 device class.
 148 .It flags
 149 The flags describe which of the fields the kernel should match against.
 150 A device must match all specified fields in order to be returned.
 151 The match flags are enumerated in the
 152 .Va pci_getconf_flags
 153 structure.
 154 Hopefully the flag values are obvious enough that they do not need to
 155 described in detail.
 156 .El
 157 .It match_buf_len
 158 Length of the
 159 .Va matches
 160 buffer allocated by the user to hold the results of the
 161 .Dv PCIOCGETCONF
 162 query.
 163 .It num_matches
 164 Number of matches returned by the kernel.
 165 .It matches
 166 Buffer containing matching devices returned by the kernel.
 167 The items in this buffer are of type
 168 .Va pci_conf ,
 169 which consists of the following items:
 170 .Bl -tag -width pc_subvendor
 171 .It pc_sel
 172 .Tn PCI
 173 domain, bus, slot and function.
 174 .It pc_hdr
 175 .Tn PCI
 176 header type.
 177 .It pc_subvendor
 178 .Tn PCI
 179 subvendor ID.
 180 .It pc_subdevice
 181 .Tn PCI
 182 subdevice ID.
 183 .It pc_vendor
 184 .Tn PCI
 185 vendor ID.
 186 .It pc_device
 187 .Tn PCI
 188 device ID.
 189 .It pc_class
 190 .Tn PCI
 191 device class.
 192 .It pc_subclass
 193 .Tn PCI
 194 device subclass.
 195 .It pc_progif
 196 .Tn PCI
 197 device programming interface.
 198 .It pc_revid
 199 .Tn PCI
 200 revision ID.
 201 .It pd_name
 202 Driver name.
 203 .It pd_unit
 204 Driver unit number.
 205 .El
 206 .It offset
 207 The offset is passed in by the user to tell the kernel where it should
 208 start traversing the device list.
 209 The value passed out by the kernel
 210 points to the record immediately after the last one returned.
 211 The user may
 212 pass the value returned by the kernel in subsequent calls to the
 213 .Dv PCIOCGETCONF
 214 ioctl.
 215 If the user does not intend to use the offset, it must be set to zero.
 216 .It generation
 217 .Tn PCI
 218 configuration generation.
 219 This value only needs to be set if the offset is set.
 220 The kernel will compare the current generation number of its internal
 221 device list to the generation passed in by the user to determine whether
 222 its device list has changed since the user last called the
 223 .Dv PCIOCGETCONF
 224 ioctl.
 225 If the device list has changed, a status of
 226 .Va PCI_GETCONF_LIST_CHANGED
 227 will be passed back.
 228 .It status
 229 The status tells the user the disposition of his request for a device list.
 230 The possible status values are:
 231 .Bl -ohang
 232 .It PCI_GETCONF_LAST_DEVICE
 233 This means that there are no more devices in the PCI device list after the
 234 ones returned in the
 235 .Va matches
 236 buffer.
 237 .It PCI_GETCONF_LIST_CHANGED
 238 This status tells the user that the
 239 .Tn PCI
 240 device list has changed since his last call to the
 241 .Dv PCIOCGETCONF
 242 ioctl and he must reset the
 243 .Va offset
 244 and
 245 .Va generation
 246 to zero to start over at the beginning of the list.
 247 .It PCI_GETCONF_MORE_DEVS
 248 This tells the user that his buffer was not large enough to hold all of the
 249 remaining devices in the device list that possibly match his criteria.
 250 It is possible for this status to be returned, even when none of the remaining
 251 devices in the list would match the user's criteria.
 252 .It PCI_GETCONF_ERROR
 253 This indicates a general error while servicing the user's request.
 254 If the
 255 .Va pat_buf_len
 256 is not equal to
 257 .Va num_patterns
 258 times
 259 .Fn sizeof "struct pci_match_conf" ,
 260 .Va errno
 261 will be set to
 262 .Er EINVAL .
 263 .El
 264 .El
 265 .It PCIOCREAD
 266 This
 267 .Xr ioctl 2
 268 reads the
 269 .Tn PCI
 270 configuration registers specified by the passed-in
 271 .Va pci_io
 272 structure.
 273 The
 274 .Va pci_io
 275 structure consists of the following fields:
 276 .Bl -tag -width pi_width
 277 .It pi_sel
 278 A
 279 .Va pcisel
 280 structure which specifies the domain, bus, slot and function the user would
 281 like to query.
 282 If the specific bus is not found, errno will be set to ENODEV and -1 returned
 283 from the ioctl.
 284 .It pi_reg
 285 The
 286 .Tn PCI
 287 configuration register the user would like to access.
 288 .It pi_width
 289 The width, in bytes, of the data the user would like to read.
 290 This value
 291 may be either 1, 2, or 4.
 292 3-byte reads and reads larger than 4 bytes are
 293 not supported.
 294 If an invalid width is passed, errno will be set to EINVAL.
 295 .It pi_data
 296 The data returned by the kernel.
 297 .El
 298 .It PCIOCWRITE
 299 This
 300 .Xr ioctl 2
 301 allows users to write to the
 302 .Tn PCI
 303 specified in the passed-in
 304 .Va pci_io
 305 structure.
 306 The
 307 .Va pci_io
 308 structure is described above.
 309 The limitations on data width described for
 310 reading registers, above, also apply to writing
 311 .Tn PCI
 312 configuration registers.
 313 .El
 314 .Sh FILES
 315 .Bl -tag -width /dev/pci -compact
 316 .It Pa /dev/pci
 317 Character device for the
 318 .Nm
 319 driver.
 320 .El
 321 .Sh SEE ALSO
 322 .Xr pciconf 8
 323 .Sh HISTORY
 324 The
 325 .Nm
 326 driver (not the kernel's
 327 .Tn PCI
 328 support code) first appeared in
 329 .Fx 2.2 ,
 330 and was written by Stefan Esser and Garrett Wollman.
 331 Support for device listing and matching was re-implemented by
 332 Kenneth Merry, and first appeared in
 333 .Fx 3.0 .
 334 .Sh AUTHORS
 335 .An Kenneth Merry Aq ken@FreeBSD.org
 336 .Sh BUGS
 337 It is not possible for users to specify an accurate offset into the device
 338 list without calling the
 339 .Dv PCIOCGETCONF
 340 at least once, since they have no way of knowing the current generation
 341 number otherwise.
 342 This probably is not a serious problem, though, since
 343 users can easily narrow their search by specifying a pattern or patterns
 344 for the kernel to match against.