Stefan Esser <se@FreeBSD.org>. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
$FreeBSD: releng/10.2/usr.sbin/pciconf/pciconf.8 262134 2014-02-17 22:19:49Z jhb $
.Dd January 20, 2014 .Dt PCICONF 8 .Os .Sh NAME .Nm pciconf .Nd diagnostic utility for the PCI bus .Sh SYNOPSIS .Nm .Fl l Oo Fl bcevV Oc Op Ar device .Nm .Fl a Ar device .Nm .Fl r Oo Fl b | h Oc Ar device addr Ns Op : Ns Ar addr2 .Nm .Fl w Oo Fl b | h Oc Ar device addr value .Sh DESCRIPTION The .Nm utility provides a command line interface to functionality provided by the .Xr pci 4 .Xr ioctl 2 interface. As such, some of the functions are only available to users with write access to
a /dev/pci , normally only the super-user.
p With the .Fl l option, .Nm lists PCI devices in the following format: d -literal foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \ hdr=0x00 bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \ hdr=0x00 none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \ hdr=0x00 .Ed
p The first column gives the driver name, unit number, and selector . If there is no driver attached to the .Tn PCI device in question, the driver name will be .Dq none . Unit numbers for detached devices start at zero and are incremented for each detached device that is encountered. The selector is in a form which may directly be used for the other forms of the command. The second column is the class code, with the class byte printed as two hex digits, followed by the sub-class and the interface bytes. The third column gives the contents of the subvendorid register, introduced in revision 2.1 of the .Tn PCI standard. Note that it will be 0 for older cards. The field consists of the card ID in the upper half and the card vendor ID in the lower half of the value.
p The fourth column contains the chip device ID, which identifies the chip this card is based on. It consists of two fields, identifying the chip and its vendor, as above. The fifth column prints the chip's revision. The sixth column describes the header type. Currently assigned header types include 0 for most devices, 1 for .Tn PCI to .Tn PCI bridges, and 2 for .Tn PCI to .Tn CardBus bridges. If the most significant bit of the header type register is set for function 0 of a .Tn PCI device, it is a .Em multi-function device, which contains several (similar or independent) functions on one chip.
p If the .Fl b option is supplied, .Nm will list any base address registers
q BARs that are assigned resources for each device. Each BAR will be enumerated via a line in the following format: d -literal bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled .Ed
p The first value after the .Dq Li bar prefix in the square brackets is the offset of the BAR in config space in hexadecimal. The type of a BAR is one of .Dq Memory , .Dq Prefetchable Memory , or .Dq I/O Port . The range indicates the maximum address the BAR decodes. The base and size indicate the start and length of the BAR's address window, respectively. Finally, the last flag indicates if the BAR is enabled or disabled.
p If the .Fl c option is supplied, .Nm will list any capabilities supported by each device. Each capability is enumerated via a line in the following format: d -literal cap 10[40] = PCI-Express 1 root port .Ed
p The first value after the .Dq Li cap prefix is the capability ID in hexadecimal. The second value in the square brackets is the offset of the capability in config space in hexadecimal. The format of the text after the equals sign is capability-specific.
p Each extended capability is enumerated via a line in a similar format: d -literal ecap 0002[100] = VC 1 max VC0 .Ed
p The first value after the .Dq Li ecap prefix is the extended capability ID in hexadecimal. The second value in the square brackets is the offset of the extended capability in config space in hexadecimal. The format of the text after the equals sign is capability-specific.
p If the .Fl e option is supplied, .Nm will list any errors reported for this device in standard PCI error registers. Errors are checked for in the PCI status register, the PCI-express device status register, and the Advanced Error Reporting status registers.
p If the .Fl v option is supplied, .Nm will attempt to load the vendor/device information database, and print vendor, device, class and subclass identification strings for each device.
p If the .Fl V option is supplied, .Nm will list any vital product data
q VPD provided by each device. Each VPD keyword is enumerated via a line in the following format: d -literal VPD ro PN = '110114640C0 ' .Ed
p The first string after the .Dq Li VPD prefix indicates if the keyword is read-only .Dq ro or read-write .Dq rw . The second string provides the keyword name. The text after the the equals sign lists the value of the keyword which is usually an ASCII string.
p If the optional .Ar device argument is given with the .Fl l flag, .Nm will only list details about a single device instead of all devices.
p All invocations of .Nm except for .Fl l require a .Ar device . The device can be identified either by a device name if the device is attached to a driver or by a selector. Selectors identify a PCI device by its address in PCI config space and can take one of the following forms:
p l -bullet -offset indent -compact t .Li pci Ns Va domain Ns : Ns Va bus Ns : Ns Va device Ns : \ Ns Va function Ns t .Li pci Ns Va bus Ns : Ns Va device Ns : Ns Va function Ns t .Li pci Ns Va bus Ns : Ns Va device Ns .El
p In the case of an abridged form, omitted selector components are assumed to be 0. An optional leading device name followed by @ and an optional final colon will be ignored; this is so that the first column in the output of .Nm .Fl l can be used without modification. All numbers are base 10.
p With the .Fl a flag, .Nm determines whether any driver has been assigned to the device identified by .Ar selector . An exit status of zero indicates that the device has a driver; non-zero indicates that it does not.
p The .Fl r option reads a configuration space register at byte offset .Ar addr of device .Ar selector and prints out its value in hexadecimal. The optional second address .Ar addr2 specifies a range to read. The .Fl w option writes the .Ar value into a configuration space register at byte offset .Ar addr of device .Ar selector . For both operations, the flags .Fl b and .Fl h select the width of the operation; .Fl b indicates a byte operation, and .Fl h indicates a halfword (two-byte) operation. The default is to read or write a longword (four bytes). .Sh ENVIRONMENT The PCI vendor/device information database is normally read from
a /usr/share/misc/pci_vendors .
This path can be overridden by setting the environment variable
.Ev PCICONF_VENDOR_DATABASE .
.Sh SEE ALSO
.Xr ioctl 2 ,
.Xr pci 4 ,
.Xr devinfo 8 ,
.Xr kldload 8
.Sh HISTORY
The
.Nm
utility appeared first in
.Fx 2.2 .
The
.Fl a
option was added for
.Tn PCI
KLD support in
.Fx 3.0 .
.Sh AUTHORS
.An -nosplit
The
.Nm
utility was written by
.An Stefan Esser
and
.An Garrett Wollman .
.Sh BUGS
The
.Fl b
and
.Fl h
options are implemented in
.Nm ,
but not in the underlying
.Xr ioctl 2 .
p It might be useful to give non-root users access to the .Fl a and .Fl r options. But only root will be able to execute a .Nm kldload to provide the device with a driver KLD, and reading of configuration space registers may cause a failure in badly designed .Tn PCI chips.