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 June 14, 2018 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.Nm 44.Fl D Oo Fl b | h | x Oc Ar device addr Op start Ns Op : Ns Ar count 45.Sh DESCRIPTION 46The 47.Nm 48utility provides a command line interface to functionality provided by the 49.Xr pci 4 50.Xr ioctl 2 51interface. 52As such, some of the functions are only available to users with write 53access to 54.Pa /dev/pci , 55normally only the super-user. 56.Pp 57With the 58.Fl l 59option, 60.Nm 61lists PCI devices in the following format: 62.Bd -literal 63foo0@pci0:0:4:0: class=0x010000 rev=0x01 hdr=0x00 vendor=0x1000 device=0x000f \ 64subvendor=0x0000 subdevice=0x0000 65bar0@pci0:0:5:0: class=0x000100 rev=0x00 hdr=0x00 vendor=0x88c1 device=0x5333 \ 66subvendor=0x0000 subdevice=0x0000 67none0@pci0:0:6:0: class=0x020000 rev=0x00 hdr=0x00 vendor=0x10ec device=0x8029 \ 68subvendor=0x0000 subdevice=0x0000 69.Ed 70.Pp 71The first column gives the 72driver name, unit number, and selector. 73If there is no driver attached to the 74.Tn PCI 75device in question, the driver name will be 76.Dq none . 77Unit numbers for detached devices start at zero and are incremented for 78each detached device that is encountered. 79The selector 80is in a form which may directly be used for the other forms of the command. 81The second column is the class code, with the class byte printed as two 82hex digits, followed by the sub-class and the interface bytes. 83The third column prints the device's revision. 84The fourth column describes the header type. 85.Pp 86Currently assigned header types include 0 for standard devices, 871 for 88.Tn PCI 89to 90.Tn PCI 91bridges, and 2 for 92.Tn PCI 93to 94.Tn CardBus 95bridges. 96If the most significant bit 97of the header type register is set for 98function 0 of a 99.Tn PCI 100device, it is a 101.Em multi-function 102device, which contains several (similar or independent) functions on 103one chip. 104.Pp 105The sixth and seventh columns contain the vendor ID and the device ID of the 106device. 107The eigth and ninth columns contain subvendor and subdevice IDs, introduced 108in revision 2.1 of the 109.Tn PCI 110standard. 111Note that they will be 0 for older cards. 112.Pp 113If the 114.Fl B 115option is supplied, 116.Nm 117will list additional information for 118.Tn PCI 119to 120.Tn PCI 121and 122.Tn PCI 123to 124.Tn CardBus 125bridges, 126specifically the resource ranges decoded by the bridge for use by devices 127behind the bridge. 128Each bridge lists a range of bus numbers handled by the bridge and its 129downstream devices. 130Memory and I/O port decoding windows are enumerated via a line in the 131following format: 132.Bd -literal 133 window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled 134.Ed 135.Pp 136The first value after the 137.Dq Li window 138prefix in the square brackets is the offset of the decoding window in 139config space in hexadecimal. 140The type of a window is one of 141.Dq Memory , 142.Dq Prefetchable Memory , 143or 144.Dq I/O Port . 145The range indicates the binary log of the maximum address the window decodes. 146The address field indicates the start and end addresses of the decoded range. 147Finally, the last flag indicates if the window is enabled or disabled. 148.Pp 149If the 150.Fl b 151option is supplied, 152.Nm 153will list any base address registers 154.Pq BARs 155that are assigned resources for each device. 156Each BAR will be enumerated via a line in the following format: 157.Bd -literal 158 bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled 159.Ed 160.Pp 161The first value after the 162.Dq Li bar 163prefix in the square brackets is the offset of the BAR in config space in 164hexadecimal. 165The type of a BAR is one of 166.Dq Memory , 167.Dq Prefetchable Memory , 168or 169.Dq I/O Port . 170The range indicates the binary log of the maximum address the BAR decodes. 171The base and size indicate the start and length of the BAR's address window, 172respectively. 173Finally, the last flag indicates if the BAR is enabled or disabled. 174.Pp 175If the 176.Fl c 177option is supplied, 178.Nm 179will list any capabilities supported by each device. 180Each capability is enumerated via a line in the following format: 181.Bd -literal 182 cap 10[40] = PCI-Express 1 root port 183.Ed 184.Pp 185The first value after the 186.Dq Li cap 187prefix is the capability ID in hexadecimal. 188The second value in the square brackets is the offset of the capability 189in config space in hexadecimal. 190The format of the text after the equals sign is capability-specific. 191.Pp 192Each extended capability is enumerated via a line in a similar format: 193.Bd -literal 194ecap 0002[100] = VC 1 max VC0 195.Ed 196.Pp 197The first value after the 198.Dq Li ecap 199prefix is the extended capability ID in hexadecimal. 200The second value in the square brackets is the offset of the extended 201capability in config space in hexadecimal. 202The format of the text after the equals sign is capability-specific. 203.Pp 204If the 205.Fl e 206option is supplied, 207.Nm 208will list any errors reported for this device in standard PCI error registers. 209Errors are checked for in the PCI status register, 210the PCI-express device status register, 211and the Advanced Error Reporting status registers. 212.Pp 213If the 214.Fl v 215option is supplied, 216.Nm 217will attempt to load the vendor/device information database, and print 218vendor, device, class and subclass identification strings for each device. 219.Pp 220If the 221.Fl V 222option is supplied, 223.Nm 224will list any vital product data 225.Pq VPD 226provided by each device. 227Each VPD keyword is enumerated via a line in the following format: 228.Bd -literal 229 VPD ro PN = '110114640C0 ' 230.Ed 231.Pp 232The first string after the 233.Dq Li VPD 234prefix indicates if the keyword is read-only 235.Dq ro 236or read-write 237.Dq rw . 238The second string provides the keyword name. 239The text after the equals sign lists the value of the keyword which is 240usually an ASCII string. 241.Pp 242If the optional 243.Ar device 244argument is given with the 245.Fl l 246flag, 247.Nm 248will only list details about a single device instead of all devices. 249.Pp 250All invocations of 251.Nm 252except for 253.Fl l 254require a 255.Ar device . 256The device can be identified either by a device name if the device is 257attached to a driver or by a selector. 258Selectors identify a PCI device by its address in PCI config space and 259can take one of the following forms: 260.Pp 261.Bl -bullet -offset indent -compact 262.It 263.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ 264Ns Va function Ns 265.It 266.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns 267.It 268.Li pci Ns Va bus Ns \&: Ns Va device Ns 269.El 270.Pp 271In the case of an abridged form, omitted selector components are assumed to be 0. 272An optional leading device name followed by @ and an optional final colon 273will be ignored; this is so that the first column in the output of 274.Nm 275.Fl l 276can be used without modification. 277All numbers are base 10. 278.Pp 279With the 280.Fl a 281flag, 282.Nm 283determines whether any driver has been assigned to the device 284identified by 285.Ar selector . 286An exit status of zero indicates that the device has a driver; 287non-zero indicates that it does not. 288.Pp 289The 290.Fl r 291option reads a configuration space register at byte offset 292.Ar addr 293of device 294.Ar selector 295and prints out its value in hexadecimal. 296The optional second address 297.Ar addr2 298specifies a range to read. 299The 300.Fl w 301option writes the 302.Ar value 303into a configuration space register at byte offset 304.Ar addr 305of device 306.Ar selector . 307.Pp 308The 309.Fl D 310option request a dump of the specified BAR. 311Dump is performed to the standard output, raw register values 312are written. 313Use 314.Xr hexdump 1 315to convert them to human-readable dump, 316or redirect into a file to save the snapshot of the device state. 317Optionally, the 318.Ar start 319and 320.Ar count 321of the registers dumped can be specified, in multiple of the operation width, 322see next paragraph. 323.Pp 324For read, write, and dump operations, the flags 325.Fl b , 326.Fl h , 327and 328.Fl x 329select the width of the operation; 330.Fl b 331indicates a byte operation, and 332.Fl h 333indicates a halfword (two-byte) operation. 334.Fl x 335indicates a quadword (four-byte) operation. 336The default is to read or 337write a longword (four bytes). 338The quadword mode is only valid for BAR dump. 339.Sh ENVIRONMENT 340PCI vendor and device information is read from 341.Pa /usr/local/share/pciids/pci.ids . 342If that file is not present, it is read from 343.Pa /usr/share/misc/pci_vendors . 344This path can be overridden by setting the environment variable 345.Ev PCICONF_VENDOR_DATABASE . 346.Sh SEE ALSO 347.Xr ioctl 2 , 348.\" .Xr pci 4 , 349.Xr devinfo 8 , 350.Xr kldload 8 351.Sh HISTORY 352The 353.Nm 354utility appeared first in 355.Fx 2.2 . 356The 357.Fl a 358option was added for 359.Tn PCI 360KLD support in 361.Fx 3.0 . 362.Sh AUTHORS 363.An -nosplit 364The 365.Nm 366utility was written by 367.An Stefan Esser 368and 369.An Garrett Wollman . 370.Sh BUGS 371The 372.Fl b 373and 374.Fl h 375options are implemented in 376.Nm , 377but not in the underlying 378.Xr ioctl 2 . 379.Pp 380It might be useful to give non-root users access to the 381.Fl a 382and 383.Fl r 384options. 385But only root will be able to execute a 386.Nm kldload 387to provide the device with a driver KLD, and reading of configuration space 388registers may cause a failure in badly designed 389.Tn PCI 390chips. 391.Pp 392There is currently no way to specify the caching mode for the mapping 393established by the 394.Fl D 395option, 396.Nm 397always uses uncached access. 398This is fine for control register BARs. 399