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: src/usr.sbin/pciconf/pciconf.8,v 1.34 2010/09/09 18:51:20 jhb Exp $ 27.\" 28.Dd March 21, 2021 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 Op Fl Bbcev 37.Nm 38.Fl a Ar selector 39.Nm 40.Fl r Oo Fl b | h Oc Ar selector addr Ns Op : Ns Ar addr2 41.Nm 42.Fl w Oo Fl b | h Oc Ar selector 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, it lists all devices found by the boot probe in the following format: 58.Bd -literal 59foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \ 60hdr=0x00 61bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \ 62hdr=0x00 63none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \ 64hdr=0x00 65.Ed 66.Pp 67The first column gives the 68device name, unit number, and 69.Ar selector . 70If there is no device configured in the kernel for the 71.Tn PCI 72device in question, the device name will be 73.Dq none . 74Unit numbers for unconfigured devices start at zero and are incremented for 75each unconfigured device that is encountered. 76The 77.Ar 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 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 221All invocations of 222.Nm 223except for 224.Fl l 225require a 226.Ar selector 227of the form 228.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ 229Ns Va function Ns , 230.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns , or 231.Li pci Ns Va bus Ns \&: Ns Va device Ns . 232In case of an abridged form, omitted selector components are assumed to be 0. 233An optional leading device name followed by @ and an optional final colon 234will be ignored; this is so that the first column in the output of 235.Nm 236.Fl l 237can be used without modification. 238All numbers are base 10. 239.Pp 240With the 241.Fl a 242flag, 243.Nm 244determines whether any driver has been assigned to the device 245identified by 246.Ar selector . 247An exit status of zero indicates that the device has a driver; 248non-zero indicates that it does not. 249.Pp 250The 251.Fl r 252option reads a configuration space register at byte offset 253.Ar addr 254of device 255.Ar selector 256and prints out its value in hexadecimal. 257The optional second address 258.Ar addr2 259specifies a range to read. 260The 261.Fl w 262option writes the 263.Ar value 264into a configuration space register at byte offset 265.Ar addr 266of device 267.Ar selector . 268For both operations, the flags 269.Fl b 270and 271.Fl h 272select the width of the operation; 273.Fl b 274indicates a byte operation, and 275.Fl h 276indicates a halfword (two-byte) operation. 277The default is to read or 278write a longword (four bytes). 279.Sh ENVIRONMENT 280The PCI vendor/device information database is normally read from 281.Pa /usr/share/misc/pci_vendors . 282This path can be overridden by setting the environment variable 283.Ev PCICONF_VENDOR_DATABASE . 284.Sh SEE ALSO 285.Xr ioctl 2 , 286.Xr pci 4 , 287.Xr devinfo 8 , 288.Xr kldload 8 289.Sh HISTORY 290The 291.Nm 292utility appeared first in 293.Fx 2.2 . 294The 295.Fl a 296option was added for 297.Tn PCI 298KLD support in 299.Fx 3.0 . 300.Sh AUTHORS 301.An -nosplit 302The 303.Nm 304utility was written by 305.An Stefan Esser 306and 307.An Garrett Wollman . 308.Sh BUGS 309The 310.Fl b 311and 312.Fl h 313options are implemented in 314.Nm , 315but not in the underlying 316.Xr ioctl 2 . 317.Pp 318It might be useful to give non-root users access to the 319.Fl a 320and 321.Fl r 322options. 323But only root will be able to execute a 324.Nm kldload 325to provide the device with a driver KLD, and reading of configuration space 326registers may cause a failure in badly designed 327.Tn PCI 328chips. 329