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 November 23, 2015 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 BbceVv 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 additional information for 119.Tn PCI 120to 121.Tn PCI 122and 123.Tn PCI 124to 125.Tn CardBus 126bridges, 127specifically the resource ranges decoded by the bridge for use by devices 128behind the bridge. 129Each bridge lists a range of bus numbers handled by the bridge and its 130downstream devices. 131Memory and I/O port decoding windows are enumerated via a line in the 132following format: 133.Bd -literal 134 window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled 135.Ed 136.Pp 137The first value after the 138.Dq Li window 139prefix in the square brackets is the offset of the decoding window in 140config space in hexadecimal. 141The type of a window is one of 142.Dq Memory , 143.Dq Prefetchable Memory , 144or 145.Dq I/O Port . 146The range indicates the binary log of the maximum address the window decodes. 147The address field indicates the start and end addresses of the decoded range. 148Finally, the last flag indicates if the window is enabled or disabled. 149.Pp 150If the 151.Fl b 152option is supplied, 153.Nm 154will list any base address registers 155.Pq BARs 156that are assigned resources for each device. 157Each BAR will be enumerated via a line in the following format: 158.Bd -literal 159 bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled 160.Ed 161.Pp 162The first value after the 163.Dq Li bar 164prefix in the square brackets is the offset of the BAR in config space in 165hexadecimal. 166The type of a BAR is one of 167.Dq Memory , 168.Dq Prefetchable Memory , 169or 170.Dq I/O Port . 171The range indicates the binary log of the maximum address the BAR decodes. 172The base and size indicate the start and length of the BAR's address window, 173respectively. 174Finally, the last flag indicates if the BAR is enabled or disabled. 175.Pp 176If the 177.Fl c 178option is supplied, 179.Nm 180will list any capabilities supported by each device. 181Each capability is enumerated via a line in the following format: 182.Bd -literal 183 cap 10[40] = PCI-Express 1 root port 184.Ed 185.Pp 186The first value after the 187.Dq Li cap 188prefix is the capability ID in hexadecimal. 189The second value in the square brackets is the offset of the capability 190in config space in hexadecimal. 191The format of the text after the equals sign is capability-specific. 192.Pp 193Each extended capability is enumerated via a line in a similar format: 194.Bd -literal 195ecap 0002[100] = VC 1 max VC0 196.Ed 197.Pp 198The first value after the 199.Dq Li ecap 200prefix is the extended capability ID in hexadecimal. 201The second value in the square brackets is the offset of the extended 202capability in config space in hexadecimal. 203The format of the text after the equals sign is capability-specific. 204.Pp 205If the 206.Fl e 207option is supplied, 208.Nm 209will list any errors reported for this device in standard PCI error registers. 210Errors are checked for in the PCI status register, 211the PCI-express device status register, 212and the Advanced Error Reporting status registers. 213.Pp 214If the 215.Fl v 216option is supplied, 217.Nm 218will attempt to load the vendor/device information database, and print 219vendor, device, class and subclass identification strings for each device. 220.Pp 221If the 222.Fl V 223option is supplied, 224.Nm 225will list any vital product data 226.Pq VPD 227provided by each device. 228Each VPD keyword is enumerated via a line in the following format: 229.Bd -literal 230 VPD ro PN = '110114640C0 ' 231.Ed 232.Pp 233The first string after the 234.Dq Li VPD 235prefix indicates if the keyword is read-only 236.Dq ro 237or read-write 238.Dq rw . 239The second string provides the keyword name. 240The text after the the equals sign lists the value of the keyword which is 241usually an ASCII string. 242.Pp 243If the optional 244.Ar device 245argument is given with the 246.Fl l 247flag, 248.Nm 249will only list details about a single device instead of all devices. 250.Pp 251All invocations of 252.Nm 253except for 254.Fl l 255require a 256.Ar device . 257The device can be identified either by a device name if the device is 258attached to a driver or by a selector. 259Selectors identify a PCI device by its address in PCI config space and 260can take one of the following forms: 261.Pp 262.Bl -bullet -offset indent -compact 263.It 264.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ 265Ns Va function Ns 266.It 267.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns 268.It 269.Li pci Ns Va bus Ns \&: Ns Va device Ns 270.El 271.Pp 272In the case of an abridged form, omitted selector components are assumed to be 0. 273An optional leading device name followed by @ and an optional final colon 274will be ignored; this is so that the first column in the output of 275.Nm 276.Fl l 277can be used without modification. 278All numbers are base 10. 279.Pp 280With the 281.Fl a 282flag, 283.Nm 284determines whether any driver has been assigned to the device 285identified by 286.Ar selector . 287An exit status of zero indicates that the device has a driver; 288non-zero indicates that it does not. 289.Pp 290The 291.Fl r 292option reads a configuration space register at byte offset 293.Ar addr 294of device 295.Ar selector 296and prints out its value in hexadecimal. 297The optional second address 298.Ar addr2 299specifies a range to read. 300The 301.Fl w 302option writes the 303.Ar value 304into a configuration space register at byte offset 305.Ar addr 306of device 307.Ar selector . 308For both operations, the flags 309.Fl b 310and 311.Fl h 312select the width of the operation; 313.Fl b 314indicates a byte operation, and 315.Fl h 316indicates a halfword (two-byte) operation. 317The default is to read or 318write a longword (four bytes). 319.Sh ENVIRONMENT 320PCI vendor and device information is read from 321.Pa /usr/local/share/pciids/pci.ids . 322If that file is not present, it is read from 323.Pa /usr/share/misc/pci_vendors . 324This path can be overridden by setting the environment variable 325.Ev PCICONF_VENDOR_DATABASE . 326.Sh SEE ALSO 327.Xr ioctl 2 , 328.\" .Xr pci 4 , 329.Xr devinfo 8 , 330.Xr kldload 8 331.Sh HISTORY 332The 333.Nm 334utility appeared first in 335.Fx 2.2 . 336The 337.Fl a 338option was added for 339.Tn PCI 340KLD support in 341.Fx 3.0 . 342.Sh AUTHORS 343.An -nosplit 344The 345.Nm 346utility was written by 347.An Stefan Esser 348and 349.An Garrett Wollman . 350.Sh BUGS 351The 352.Fl b 353and 354.Fl h 355options are implemented in 356.Nm , 357but not in the underlying 358.Xr ioctl 2 . 359.Pp 360It might be useful to give non-root users access to the 361.Fl a 362and 363.Fl r 364options. 365But only root will be able to execute a 366.Nm kldload 367to provide the device with a driver KLD, and reading of configuration space 368registers may cause a failure in badly designed 369.Tn PCI 370chips. 371