1.\" Copyright (c) 1997 2.\" Stefan Esser <se@FreeBSD.org>. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd January 20, 2014 29.Dt PCICONF 8 30.Os 31.Sh NAME 32.Nm pciconf 33.Nd diagnostic utility for the PCI bus 34.Sh SYNOPSIS 35.Nm 36.Fl l Oo Fl bcevV Oc Op Ar device 37.Nm 38.Fl a Ar device 39.Nm 40.Fl r Oo Fl b | h Oc Ar device addr Ns Op : Ns Ar addr2 41.Nm 42.Fl w Oo Fl b | h Oc Ar device addr value 43.Sh DESCRIPTION 44The 45.Nm 46utility provides a command line interface to functionality provided by the 47.Xr pci 4 48.Xr ioctl 2 49interface. 50As such, some of the functions are only available to users with write 51access to 52.Pa /dev/pci , 53normally only the super-user. 54.Pp 55With the 56.Fl l 57option, 58.Nm 59lists PCI devices in the following format: 60.Bd -literal 61foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \ 62hdr=0x00 63bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \ 64hdr=0x00 65none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \ 66hdr=0x00 67.Ed 68.Pp 69The first column gives the 70driver name, unit number, and selector . 71If there is no driver attached to the 72.Tn PCI 73device in question, the driver name will be 74.Dq none . 75Unit numbers for detached devices start at zero and are incremented for 76each detached device that is encountered. 77The selector 78is in a form which may directly be used for the other forms of the command. 79The second column is the class code, with the class byte printed as two 80hex digits, followed by the sub-class and the interface bytes. 81The third column gives the contents of the subvendorid register, introduced 82in revision 2.1 of the 83.Tn PCI 84standard. 85Note that it will be 0 for older cards. 86The field consists of the card ID in the upper 87half and the card vendor ID in the lower half of the value. 88.Pp 89The fourth column contains the chip device ID, which identifies the chip 90this card is based on. 91It consists of two fields, identifying the chip and 92its vendor, as above. 93The fifth column prints the chip's revision. 94The sixth column describes the header type. 95Currently assigned header types include 0 for most devices, 961 for 97.Tn PCI 98to 99.Tn PCI 100bridges, and 2 for 101.Tn PCI 102to 103.Tn CardBus 104bridges. 105If the most significant bit 106of the header type register is set for 107function 0 of a 108.Tn PCI 109device, it is a 110.Em multi-function 111device, which contains several (similar or independent) functions on 112one chip. 113.Pp 114If the 115.Fl b 116option is supplied, 117.Nm 118will list any base address registers 119.Pq BARs 120that are assigned resources for each device. 121Each BAR will be enumerated via a line in the following format: 122.Bd -literal 123 bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled 124.Ed 125.Pp 126The first value after the 127.Dq Li bar 128prefix in the square brackets is the offset of the BAR in config space in 129hexadecimal. 130The type of a BAR is one of 131.Dq Memory , 132.Dq Prefetchable Memory , 133or 134.Dq I/O Port . 135The range indicates the maximum address the BAR decodes. 136The base and size indicate the start and length of the BAR's address window, 137respectively. 138Finally, the last flag indicates if the BAR is enabled or disabled. 139.Pp 140If the 141.Fl c 142option is supplied, 143.Nm 144will list any capabilities supported by each device. 145Each capability is enumerated via a line in the following format: 146.Bd -literal 147 cap 10[40] = PCI-Express 1 root port 148.Ed 149.Pp 150The first value after the 151.Dq Li cap 152prefix is the capability ID in hexadecimal. 153The second value in the square brackets is the offset of the capability 154in config space in hexadecimal. 155The format of the text after the equals sign is capability-specific. 156.Pp 157Each extended capability is enumerated via a line in a similar format: 158.Bd -literal 159ecap 0002[100] = VC 1 max VC0 160.Ed 161.Pp 162The first value after the 163.Dq Li ecap 164prefix is the extended capability ID in hexadecimal. 165The second value in the square brackets is the offset of the extended 166capability in config space in hexadecimal. 167The format of the text after the equals sign is capability-specific. 168.Pp 169If the 170.Fl e 171option is supplied, 172.Nm 173will list any errors reported for this device in standard PCI error registers. 174Errors are checked for in the PCI status register, 175the PCI-express device status register, 176and the Advanced Error Reporting status registers. 177.Pp 178If the 179.Fl v 180option is supplied, 181.Nm 182will attempt to load the vendor/device information database, and print 183vendor, device, class and subclass identification strings for each device. 184.Pp 185If the 186.Fl V 187option is supplied, 188.Nm 189will list any vital product data 190.Pq VPD 191provided by each device. 192Each VPD keyword is enumerated via a line in the following format: 193.Bd -literal 194 VPD ro PN = '110114640C0 ' 195.Ed 196.Pp 197The first string after the 198.Dq Li VPD 199prefix indicates if the keyword is read-only 200.Dq ro 201or read-write 202.Dq rw . 203The second string provides the keyword name. 204The text after the the equals sign lists the value of the keyword which is 205usually an ASCII string. 206.Pp 207If the optional 208.Ar device 209argument is given with the 210.Fl l 211flag, 212.Nm 213will only list details about a single device instead of all devices. 214.Pp 215All invocations of 216.Nm 217except for 218.Fl l 219require a 220.Ar device . 221The device can be identified either by a device name if the device is 222attached to a driver or by a selector. 223Selectors identify a PCI device by its address in PCI config space and 224can take one of the following forms: 225.Pp 226.Bl -bullet -offset indent -compact 227.It 228.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ 229Ns Va function Ns 230.It 231.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns 232.It 233.Li pci Ns Va bus Ns \&: Ns Va device Ns 234.El 235.Pp 236In the case of an abridged form, omitted selector components are assumed to be 0. 237An optional leading device name followed by @ and an optional final colon 238will be ignored; this is so that the first column in the output of 239.Nm 240.Fl l 241can be used without modification. 242All numbers are base 10. 243.Pp 244With the 245.Fl a 246flag, 247.Nm 248determines whether any driver has been assigned to the device 249identified by 250.Ar selector . 251An exit status of zero indicates that the device has a driver; 252non-zero indicates that it does not. 253.Pp 254The 255.Fl r 256option reads a configuration space register at byte offset 257.Ar addr 258of device 259.Ar selector 260and prints out its value in hexadecimal. 261The optional second address 262.Ar addr2 263specifies a range to read. 264The 265.Fl w 266option writes the 267.Ar value 268into a configuration space register at byte offset 269.Ar addr 270of device 271.Ar selector . 272For both operations, the flags 273.Fl b 274and 275.Fl h 276select the width of the operation; 277.Fl b 278indicates a byte operation, and 279.Fl h 280indicates a halfword (two-byte) operation. 281The default is to read or 282write a longword (four bytes). 283.Sh ENVIRONMENT 284The PCI vendor/device information database is normally read from 285.Pa /usr/share/misc/pci_vendors . 286This path can be overridden by setting the environment variable 287.Ev PCICONF_VENDOR_DATABASE . 288.Sh SEE ALSO 289.Xr ioctl 2 , 290.\" .Xr pci 4 , 291.Xr devinfo 8 , 292.Xr kldload 8 293.Sh HISTORY 294The 295.Nm 296utility appeared first in 297.Fx 2.2 . 298The 299.Fl a 300option was added for 301.Tn PCI 302KLD support in 303.Fx 3.0 . 304.Sh AUTHORS 305.An -nosplit 306The 307.Nm 308utility was written by 309.An Stefan Esser 310and 311.An Garrett Wollman . 312.Sh BUGS 313The 314.Fl b 315and 316.Fl h 317options are implemented in 318.Nm , 319but not in the underlying 320.Xr ioctl 2 . 321.Pp 322It might be useful to give non-root users access to the 323.Fl a 324and 325.Fl r 326options. 327But only root will be able to execute a 328.Nm kldload 329to provide the device with a driver KLD, and reading of configuration space 330registers may cause a failure in badly designed 331.Tn PCI 332chips. 333