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 August 9, 2016
  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 matching
 233 the specified criteria 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 match his criteria.
 250 .It PCI_GETCONF_ERROR
 251 This indicates a general error while servicing the user's request.
 252 If the
 253 .Va pat_buf_len
 254 is not equal to
 255 .Va num_patterns
 256 times
 257 .Fn sizeof "struct pci_match_conf" ,
 258 .Va errno
 259 will be set to
 260 .Er EINVAL .
 261 .El
 262 .El
 263 .It PCIOCREAD
 264 This
 265 .Xr ioctl 2
 266 reads the
 267 .Tn PCI
 268 configuration registers specified by the passed-in
 269 .Va pci_io
 270 structure.
 271 The
 272 .Va pci_io
 273 structure consists of the following fields:
 274 .Bl -tag -width pi_width
 275 .It pi_sel
 276 A
 277 .Va pcisel
 278 structure which specifies the domain, bus, slot and function the user would
 279 like to query.
 280 If the specific bus is not found, errno will be set to ENODEV and -1 returned
 281 from the ioctl.
 282 .It pi_reg
 283 The
 284 .Tn PCI
 285 configuration register the user would like to access.
 286 .It pi_width
 287 The width, in bytes, of the data the user would like to read.
 288 This value
 289 may be either 1, 2, or 4.
 290 3-byte reads and reads larger than 4 bytes are
 291 not supported.
 292 If an invalid width is passed, errno will be set to EINVAL.
 293 .It pi_data
 294 The data returned by the kernel.
 295 .El
 296 .It PCIOCWRITE
 297 This
 298 .Xr ioctl 2
 299 allows users to write to the
 300 .Tn PCI
 301 specified in the passed-in
 302 .Va pci_io
 303 structure.
 304 The
 305 .Va pci_io
 306 structure is described above.
 307 The limitations on data width described for
 308 reading registers, above, also apply to writing
 309 .Tn PCI
 310 configuration registers.
 311 .El
 312 .Sh FILES
 313 .Bl -tag -width /dev/pci -compact
 314 .It Pa /dev/pci
 315 Character device for the
 316 .Nm
 317 driver.
 318 .El
 319 .Sh SEE ALSO
 320 .Xr pciconf 8
 321 .Sh HISTORY
 322 The
 323 .Nm
 324 driver (not the kernel's
 325 .Tn PCI
 326 support code) first appeared in
 327 .Fx 2.2 ,
 328 and was written by Stefan Esser and Garrett Wollman.
 329 Support for device listing and matching was re-implemented by
 330 Kenneth Merry, and first appeared in
 331 .Fx 3.0 .
 332 .Sh AUTHORS
 333 .An Kenneth Merry Aq ken@FreeBSD.org
 334 .Sh BUGS
 335 It is not possible for users to specify an accurate offset into the device
 336 list without calling the
 337 .Dv PCIOCGETCONF
 338 at least once, since they have no way of knowing the current generation
 339 number otherwise.
 340 This probably is not a serious problem, though, since
 341 users can easily narrow their search by specifying a pattern or patterns
 342 for the kernel to match against.