NAME
pciconf
—
diagnostic utility for the PCI
bus
SYNOPSIS
pciconf |
-l [-BbceVv ]
[device] |
pciconf |
-a device |
pciconf |
-r [-b |
-h ] device
addr[:addr2] |
pciconf |
-w [-b |
-h ] device addr value |
pciconf |
-D [-b |
-h | -x ]
device addr
[start[:count]] |
DESCRIPTION
Thepciconf
utility provides a command line interface to
functionality provided by the
pci(4) ioctl(2) interface. As such, some of the functions are only
available to users with write access to /dev/pci,
normally only the super-user.
With the -l
option,
pciconf
lists PCI devices in the following
format:
foo0@pci0:0:4:0: class=0x010000 rev=0x01 hdr=0x00 vendor=0x1000 device=0x000f subvendor=0x0000 subdevice=0x0000 bar0@pci0:0:5:0: class=0x000100 rev=0x00 hdr=0x00 vendor=0x88c1 device=0x5333 subvendor=0x0000 subdevice=0x0000 none0@pci0:0:6:0: class=0x020000 rev=0x00 hdr=0x00 vendor=0x10ec device=0x8029 subvendor=0x0000 subdevice=0x0000
The first column gives the driver name, unit number, and selector. If there is no driver attached to the PCI device in question, the driver name will be “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 prints the device's revision. The fourth column describes the header type.
Currently assigned header types include 0 for standard devices, 1 for PCI to PCI bridges, and 2 for PCI to CardBus bridges. If the most significant bit of the header type register is set for function 0 of a PCI device, it is a multi-function device, which contains several (similar or independent) functions on one chip.
The sixth and seventh columns contain the vendor ID and the device ID of the device. The eigth and ninth columns contain subvendor and subdevice IDs, introduced in revision 2.1 of the PCI standard. Note that they will be 0 for older cards.
Adding a second -l
option causes output to
be in a compact columnar format, suitable for 80 column output:
drv selector class rev hdr vendor device subven subdev foo0@pci0:0:4:0: 010000 01 00 1000 000f 0000 0000 bar0@pci0:0:5:0: 000100 00 00 88c1 5333 0000 0000 none0@pci0:0:6:0: 020000 00 00 10ec 8029 0000 0000
All fields retain the same definition as with the non-compact form.
If the -B
option is supplied,
pciconf
will list additional information for PCI to
PCI and PCI to CardBus bridges, specifically the resource ranges decoded by
the bridge for use by devices behind the bridge. Each bridge lists a range
of bus numbers handled by the bridge and its downstream devices. Memory and
I/O port decoding windows are enumerated via a line in the following
format:
window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled
The first value after the
“window
” prefix in the square brackets
is the offset of the decoding window in config space in hexadecimal. The
type of a window is one of “Memory”, “Prefetchable
Memory”, or “I/O Port”. The range indicates the binary
log of the maximum address the window decodes. The address field indicates
the start and end addresses of the decoded range. Finally, the last flag
indicates if the window is enabled or disabled.
If the -b
option is supplied,
pciconf
will list any base address registers (BARs)
that are assigned resources for each device. Each BAR will be enumerated via
a line in the following format:
bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled
The first value after the
“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 “Memory”, “Prefetchable Memory”, or
“I/O Port”. The range indicates the binary log of 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.
If the -c
option is supplied,
pciconf
will list any capabilities supported by each
device. A second invocation of -c
will print
additional data for certain capabilities. Each capability is enumerated via
a line in the following format:
cap 10[40] = PCI-Express 1 root port
The first value after the
“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.
Each extended capability is enumerated via a line in a similar format:
ecap 0002[100] = VC 1 max VC0
The first value after the
“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.
If the -e
option is supplied,
pciconf
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.
If the -v
option is supplied,
pciconf
will attempt to load the vendor/device
information database, and print vendor, device, class and subclass
identification strings for each device.
If the -V
option is supplied,
pciconf
will list any vital product data (VPD)
provided by each device. Each VPD keyword is enumerated via a line in the
following format:
VPD ro PN = '110114640C0 '
The first string after the
“VPD
” prefix indicates if the keyword
is read-only “ro” or read-write “rw”. The second
string provides the keyword name. The text after the equals sign lists the
value of the keyword which is usually an ASCII string.
If the optional device argument is given
with the -l
flag, pciconf
will only list details about a single device instead of all devices.
All invocations of pciconf
except for
-l
require a 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:
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 pciconf
-l
can
be used without modification. All numbers are base 10.
With the -a
flag,
pciconf
determines whether any driver has been
assigned to the device identified by selector. An exit
status of zero indicates that the device has a driver; non-zero indicates
that it does not.
The -r
option reads a configuration space
register at byte offset addr of device
selector and prints out its value in hexadecimal. The
optional second address addr2 specifies a range to
read. The -w
option writes the
value into a configuration space register at byte
offset addr of device
selector.
The -D
option request a dump of the
specified BAR. Dump is performed to the standard output, raw register values
are written. Use
hexdump(1) to convert them to human-readable dump, or redirect into a
file to save the snapshot of the device state. Optionally, the
start and count of the registers
dumped can be specified, in multiple of the operation width, see next
paragraph.
For read, write, and dump operations, the flags
-b
, -h
, and
-x
select the width of the operation;
-b
indicates a byte operation, and
-h
indicates a halfword (two-byte) operation.
-x
indicates a quadword (four-byte) operation. The
default is to read or write a longword (four bytes). The quadword mode is
only valid for BAR dump.
ENVIRONMENT
PCI vendor and device information is read from
/usr/local/share/pciids/pci.ids. If that file is not
present, it is read from
/usr/share/misc/pci_vendors. This path can be
overridden by setting the environment variable
PCICONF_VENDOR_DATABASE
.
SEE ALSO
HISTORY
The pciconf
utility appeared first in
FreeBSD 2.2. The -a
option
was added for PCI KLD support in FreeBSD 3.0.
AUTHORS
The pciconf
utility was written by
Stefan Esser and Garrett
Wollman.
BUGS
The -b
and -h
options are implemented in pciconf
, but not in the
underlying ioctl(2).
It might be useful to give non-root users access to the
-a
and -r
options. But only
root will be able to execute a kldload
to provide
the device with a driver KLD, and reading of configuration space registers
may cause a failure in badly designed PCI chips.
There is currently no way to specify the caching mode for the
mapping established by the -D
option,
pciconf
always uses uncached access. This is fine
for control register BARs.