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 September 8, 2016 28.Dt PCI 4 29.Os 30.Sh NAME 31.Nm pci 32.Nd generic PCI bus driver 33.Sh SYNOPSIS 34To compile the PCI bus driver into the kernel, 35place the following line in your 36kernel configuration file: 37.Bd -ragged -offset indent 38.Cd device pci 39.Ed 40.Pp 41To compile in support for Single Root I/O Virtualization 42.Pq SR-IOV : 43.Bd -ragged -offset indent 44.Cd options PCI_IOV 45.Ed 46.Pp 47To compile in support for native PCI-express HotPlug: 48.Bd -ragged -offset indent 49.Cd options PCI_HP 50.Ed 51.Sh DESCRIPTION 52The 53.Nm 54driver provides support for 55.Tn PCI 56devices in the kernel and limited access to 57.Tn PCI 58devices for userland. 59.Pp 60The 61.Nm 62driver provides a 63.Pa /dev/pci 64character device that can be used by userland programs to read and write 65.Tn PCI 66configuration registers. 67Programs can also use this device to get a list of all 68.Tn PCI 69devices, or all 70.Tn PCI 71devices that match various patterns. 72.Pp 73Since the 74.Nm 75driver provides a write interface for 76.Tn PCI 77configuration registers, system administrators should exercise caution when 78granting access to the 79.Nm 80device. 81If used improperly, this driver can allow userland applications to 82crash a machine or cause data loss. 83.Pp 84The 85.Nm 86driver implements the 87.Tn PCI 88bus in the kernel. 89It enumerates any devices on the 90.Tn PCI 91bus and gives 92.Tn PCI 93client drivers the chance to attach to them. 94It assigns resources to children, when the BIOS does not. 95It takes care of routing interrupts when necessary. 96It reprobes the unattached 97.Tn PCI 98children when 99.Tn PCI 100client drivers are dynamically 101loaded at runtime. 102The 103.Nm 104driver also includes support for PCI-PCI bridges, 105various platform-specific Host-PCI bridges, 106and basic support for 107.Tn PCI 108VGA adapters. 109.Sh IOCTLS 110The following 111.Xr ioctl 2 112calls are supported by the 113.Nm 114driver. 115They are defined in the header file 116.In sys/pciio.h . 117.Bl -tag -width 012345678901234 118.It PCIOCGETCONF 119This 120.Xr ioctl 2 121takes a 122.Va pci_conf_io 123structure. 124It allows the user to retrieve information on all 125.Tn PCI 126devices in the system, or on 127.Tn PCI 128devices matching patterns supplied by the user. 129The call may set 130.Va errno 131to any value specified in either 132.Xr copyin 9 133or 134.Xr copyout 9 . 135The 136.Va pci_conf_io 137structure consists of a number of fields: 138.Bl -tag -width match_buf_len 139.It pat_buf_len 140The length, in bytes, of the buffer filled with user-supplied patterns. 141.It num_patterns 142The number of user-supplied patterns. 143.It patterns 144Pointer to a buffer filled with user-supplied patterns. 145.Va patterns 146is a pointer to 147.Va num_patterns 148.Va pci_match_conf 149structures. 150The 151.Va pci_match_conf 152structure consists of the following elements: 153.Bl -tag -width pd_vendor 154.It pc_sel 155.Tn PCI 156domain, bus, slot and function. 157.It pd_name 158.Tn PCI 159device driver name. 160.It pd_unit 161.Tn PCI 162device driver unit number. 163.It pc_vendor 164.Tn PCI 165vendor ID. 166.It pc_device 167.Tn PCI 168device ID. 169.It pc_class 170.Tn PCI 171device class. 172.It flags 173The flags describe which of the fields the kernel should match against. 174A device must match all specified fields in order to be returned. 175The match flags are enumerated in the 176.Va pci_getconf_flags 177structure. 178Hopefully the flag values are obvious enough that they do not need to 179described in detail. 180.El 181.It match_buf_len 182Length of the 183.Va matches 184buffer allocated by the user to hold the results of the 185.Dv PCIOCGETCONF 186query. 187.It num_matches 188Number of matches returned by the kernel. 189.It matches 190Buffer containing matching devices returned by the kernel. 191The items in this buffer are of type 192.Va pci_conf , 193which consists of the following items: 194.Bl -tag -width pc_subvendor 195.It pc_sel 196.Tn PCI 197domain, bus, slot and function. 198.It pc_hdr 199.Tn PCI 200header type. 201.It pc_subvendor 202.Tn PCI 203subvendor ID. 204.It pc_subdevice 205.Tn PCI 206subdevice ID. 207.It pc_vendor 208.Tn PCI 209vendor ID. 210.It pc_device 211.Tn PCI 212device ID. 213.It pc_class 214.Tn PCI 215device class. 216.It pc_subclass 217.Tn PCI 218device subclass. 219.It pc_progif 220.Tn PCI 221device programming interface. 222.It pc_revid 223.Tn PCI 224revision ID. 225.It pd_name 226Driver name. 227.It pd_unit 228Driver unit number. 229.El 230.It offset 231The offset is passed in by the user to tell the kernel where it should 232start traversing the device list. 233The value passed out by the kernel 234points to the record immediately after the last one returned. 235The user may 236pass the value returned by the kernel in subsequent calls to the 237.Dv PCIOCGETCONF 238ioctl. 239If the user does not intend to use the offset, it must be set to zero. 240.It generation 241.Tn PCI 242configuration generation. 243This value only needs to be set if the offset is set. 244The kernel will compare the current generation number of its internal 245device list to the generation passed in by the user to determine whether 246its device list has changed since the user last called the 247.Dv PCIOCGETCONF 248ioctl. 249If the device list has changed, a status of 250.Va PCI_GETCONF_LIST_CHANGED 251will be passed back. 252.It status 253The status tells the user the disposition of his request for a device list. 254The possible status values are: 255.Bl -ohang 256.It PCI_GETCONF_LAST_DEVICE 257This means that there are no more devices in the PCI device list matching 258the specified criteria after the 259ones returned in the 260.Va matches 261buffer. 262.It PCI_GETCONF_LIST_CHANGED 263This status tells the user that the 264.Tn PCI 265device list has changed since his last call to the 266.Dv PCIOCGETCONF 267ioctl and he must reset the 268.Va offset 269and 270.Va generation 271to zero to start over at the beginning of the list. 272.It PCI_GETCONF_MORE_DEVS 273This tells the user that his buffer was not large enough to hold all of the 274remaining devices in the device list that match his criteria. 275.It PCI_GETCONF_ERROR 276This indicates a general error while servicing the user's request. 277If the 278.Va pat_buf_len 279is not equal to 280.Va num_patterns 281times 282.Fn sizeof "struct pci_match_conf" , 283.Va errno 284will be set to 285.Er EINVAL . 286.El 287.El 288.It PCIOCREAD 289This 290.Xr ioctl 2 291reads the 292.Tn PCI 293configuration registers specified by the passed-in 294.Va pci_io 295structure. 296The 297.Va pci_io 298structure consists of the following fields: 299.Bl -tag -width pi_width 300.It pi_sel 301A 302.Va pcisel 303structure which specifies the domain, bus, slot and function the user would 304like to query. 305If the specific bus is not found, errno will be set to ENODEV and -1 returned 306from the ioctl. 307.It pi_reg 308The 309.Tn PCI 310configuration register the user would like to access. 311.It pi_width 312The width, in bytes, of the data the user would like to read. 313This value 314may be either 1, 2, or 4. 3153-byte reads and reads larger than 4 bytes are 316not supported. 317If an invalid width is passed, errno will be set to EINVAL. 318.It pi_data 319The data returned by the kernel. 320.El 321.It PCIOCWRITE 322This 323.Xr ioctl 2 324allows users to write to the 325.Tn PCI 326specified in the passed-in 327.Va pci_io 328structure. 329The 330.Va pci_io 331structure is described above. 332The limitations on data width described for 333reading registers, above, also apply to writing 334.Tn PCI 335configuration registers. 336.El 337.Sh LOADER TUNABLES 338Tunables can be set at the 339.Xr loader 8 340prompt before booting the kernel, or stored in 341.Xr loader.conf 5 . 342The current value of these tunables can be examined at runtime via 343.Xr sysctl 8 344nodes of the same name. 345Unless otherwise specified, 346each of these tunables is a boolean that can be enabled by setting the 347tunable to a non-zero value. 348.Bl -tag -width indent 349.It Va hw.pci.clear_bars Pq Defaults to 0 350Ignore any firmware-assigned memory and I/O port resources. 351This forces the 352.Tn PCI 353bus driver to allocate resource ranges for memory and I/O port resources 354from scratch. 355.It Va hw.pci.clear_buses Pq Defaults to 0 356Ignore any firmware-assigned bus number registers in PCI-PCI bridges. 357This forces the 358.Tn PCI 359bus driver and PCI-PCI bridge driver to allocate bus numbers for secondary 360buses behind PCI-PCI bridges. 361.It Va hw.pci.clear_pcib Pq Defaults to 0 362Ignore any firmware-assigned memory and I/O port resource windows in PCI-PCI 363bridges. 364This forces the PCI-PCI bridge driver to allocate memory and I/O port resources 365for resource windows from scratch. 366.Pp 367By default the PCI-PCI bridge driver will allocate windows that 368contain the firmware-assigned resources devices behind the bridge. 369In addition, the PCI-PCI bridge driver will suballocate from existing window 370regions when possible to satisfy a resource request. 371As a result, 372both 373.Va hw.pci.clear_bars 374and 375.Va hw.pci.clear_pcib 376must be enabled to fully ignore firmware-supplied resource assignments. 377.It Va hw.pci.default_vgapci_unit Pq Defaults to -1 378By default, 379the first 380.Tn PCI 381VGA adapter encountered by the system is assumed to be the boot display device. 382This tunable can be set to choose a specific VGA adapter by specifying the 383unit number of the associated 384.Va vgapci Ns Ar X 385device. 386.It Va hw.pci.do_power_nodriver Pq Defaults to 0 387Place devices into a low power state 388.Pq D3 389when a suitable device driver is not found. 390Can be set to one of the following values: 391.Bl -tag -width indent 392.It 3 393Powers down all 394.Tn PCI 395devices without a device driver. 396.It 2 397Powers down most devices without a device driver. 398PCI devices with the display, memory, and base peripheral device classes 399are not powered down. 400.It 1 401Similar to a setting of 2 except that storage controllers are also not 402powered down. 403.It 0 404All devices are left fully powered. 405.El 406.Pp 407A 408.Tn PCI 409device must support power management to be powered down. 410Placing a device into a low power state may not reduce power consumption. 411.It Va hw.pci.do_power_resume Pq Defaults to 1 412Place 413.Tn PCI 414devices into the fully powered state when resuming either the system or an 415individual device. 416Setting this to zero is discouraged as the system will not attempt to power 417up non-powered PCI devices after a suspend. 418.It Va hw.pci.do_power_suspend Pq Defaults to 1 419Place 420.Tn PCI 421devices into a low power state when suspending either the system or individual 422devices. 423Normally the D3 state is used as the low power state, 424but firmware may override the desired power state during a system suspend. 425.It Va hw.pci.enable_ari Pq Defaults to 1 426Enable support for PCI-express Alternative RID Interpretation. 427This is often used in conjunction with SR-IOV. 428.It Va hw.pci.enable_io_modes Pq Defaults to 1 429Enable memory or I/O port decoding in a PCI device's command register if it has 430firmware-assigned memory or I/O port resources. 431The firmware 432.Pq BIOS 433in some systems does not enable memory or I/O port decoding for some devices 434even when it has assigned resources to the device. 435This enables decoding for such resources during bus probe. 436.It Va hw.pci.enable_msi Pq Defaults to 1 437Enable support for Message Signalled Interrupts 438.Pq MSI . 439MSI interrupts can be disabled by setting this tunable to 0. 440.It Va hw.pci.enable_msix Pq Defaults to 1 441Enable support for extended Message Signalled Interrupts 442.Pq MSI-X . 443MSI-X interrupts can be disabled by setting this tunable to 0. 444.It Va hw.pci.enable_pcie_hp Pq Defaults to 1 445Enable support for native PCI-express HotPlug. 446.It Va hw.pci.honor_msi_blacklist Pq Defaults to 1 447MSI and MSI-X interrupts are disabled for certain chipsets known to have 448broken MSI and MSI-X implementations when this tunable is set. 449It can be set to zero to permit use of MSI and MSI-X interrupts if the 450chipset match is a false positive. 451.It Va hw.pci.iov_max_config Pq Defaults to 1MB 452The maximum amount of memory permitted for the configuration parameters 453used when creating Virtual Functions via SR-IOV. 454This tunable can also be changed at runtime via 455.Xr sysctl 8 . 456.It Va hw.pci.realloc_bars Pq Defaults to 0 457Attempt to allocate a new resource range during the initial device scan 458for any memory or I/O port resources with firmware-assigned ranges that 459conflict with another active resource. 460.It Va hw.pci.usb_early_takeover Pq Defaults to 1 on Tn amd64 and Tn i386 461Disable legacy device emulation of USB devices during the initial device 462scan. 463Set this tunable to zero to use USB devices via legacy emulation when 464using a custom kernel without USB controller drivers. 465.It Va hw.pci<D>.<B>.<S>.INT<P>.irq 466These tunables can be used to override the interrupt routing for legacy 467PCI INTx interrupts. 468Unlike other tunables in this list, 469these do not have corresponding sysctl nodes. 470The tunable name includes the address of the PCI device as well as the 471pin of the desired INTx IRQ to override: 472.Bl -tag -width indent 473.It <D> 474The domain 475.Pq or segment 476of the PCI device in decimal. 477.It <B> 478The bus address of the PCI device in decimal. 479.It <S> 480The slot of the PCI device in decimal. 481.It <P> 482The interrupt pin of the PCI slot to override. 483One of 484.Ql A , 485.Ql B , 486.Ql C , 487or 488.Ql D . 489.El 490.Pp 491The value of the tunable is the raw IRQ value to use for the INTx interrupt 492pin identified by the tunable name. 493Mapping of IRQ values to platform interrupt sources is machine dependent. 494.El 495.Sh FILES 496.Bl -tag -width /dev/pci -compact 497.It Pa /dev/pci 498Character device for the 499.Nm 500driver. 501.El 502.Sh SEE ALSO 503.Xr pciconf 8 504.Sh HISTORY 505The 506.Nm 507driver (not the kernel's 508.Tn PCI 509support code) first appeared in 510.Fx 2.2 , 511and was written by Stefan Esser and Garrett Wollman. 512Support for device listing and matching was re-implemented by 513Kenneth Merry, and first appeared in 514.Fx 3.0 . 515.Sh AUTHORS 516.An Kenneth Merry Aq Mt ken@FreeBSD.org 517.Sh BUGS 518It is not possible for users to specify an accurate offset into the device 519list without calling the 520.Dv PCIOCGETCONF 521at least once, since they have no way of knowing the current generation 522number otherwise. 523This probably is not a serious problem, though, since 524users can easily narrow their search by specifying a pattern or patterns 525for the kernel to match against. 526