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