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 7, 2007 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 cv 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 c 116option is supplied, 117.Nm 118will list any capabilities supported by each device. 119Each capability will be enumerated via a line in the following format: 120.Bd -literal 121 cap 10[40] = PCI-Express 1 root port 122.Ed 123.Pp 124The first value after the 125.Dq Li cap 126prefix is the capability ID in hexadecimal. 127The second value in the square brackets is the offset of the capability 128in config space in hexadecimal. 129The format of the text after the equals sign is capability-specific. 130.Pp 131If the 132.Fl v 133option is supplied, 134.Nm 135will attempt to load the vendor/device information database, and print 136vendor, device, class and subclass identification strings for each device. 137.Pp 138All invocations of 139.Nm 140except for 141.Fl l 142require a 143.Ar selector 144of the form 145.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \ 146Ns Va function Ns , 147.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns , or 148.Li pci Ns Va bus Ns \&: Ns Va device Ns . 149In case of an abrigded form, omitted selector components are assumed to be 0. 150An optional leading device name followed by @ and an optional final colon 151will be ignored; this is so that the first column in the output of 152.Nm 153.Fl l 154can be used without modification. 155All numbers are base 10. 156.Pp 157With the 158.Fl a 159flag, 160.Nm 161determines whether any driver has been assigned to the device 162identified by 163.Ar selector . 164An exit status of zero indicates that the device has a driver; 165non-zero indicates that it does not. 166.Pp 167The 168.Fl r 169option reads a configuration space register at byte offset 170.Ar addr 171of device 172.Ar selector 173and prints out its value in hexadecimal. 174The optional second address 175.Ar addr2 176specifies a range to read. 177The 178.Fl w 179option writes the 180.Ar value 181into a configuration space register at byte offset 182.Ar addr 183of device 184.Ar selector . 185For both operations, the flags 186.Fl b 187and 188.Fl h 189select the width of the operation; 190.Fl b 191indicates a byte operation, and 192.Fl h 193indicates a halfword (two-byte) operation. 194The default is to read or 195write a longword (four bytes). 196.Sh ENVIRONMENT 197The PCI vendor/device information database is normally read from 198.Pa /usr/share/misc/pci_vendors . 199This path can be overridden by setting the environment variable 200.Ev PCICONF_VENDOR_DATABASE . 201.Sh SEE ALSO 202.Xr ioctl 2 , 203.\" .Xr pci 4 , 204.Xr devinfo 8 , 205.Xr kldload 8 206.Sh HISTORY 207The 208.Nm 209utility appeared first in 210.Fx 2.2 . 211The 212.Fl a 213option was added for 214.Tn PCI 215KLD support in 216.Fx 3.0 . 217.Sh AUTHORS 218.An -nosplit 219The 220.Nm 221utility was written by 222.An Stefan Esser 223and 224.An Garrett Wollman . 225.Sh BUGS 226The 227.Fl b 228and 229.Fl h 230options are implemented in 231.Nm , 232but not in the underlying 233.Xr ioctl 2 . 234.Pp 235It might be useful to give non-root users access to the 236.Fl a 237and 238.Fl r 239options. 240But only root will be able to execute a 241.Nm kldload 242to provide the device with a driver KLD, and reading of configuration space 243registers may cause a failure in badly designed 244.Tn PCI 245chips. 246