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