path: root/usr.sbin/pciconf/pciconf.8

.\" $FreeBSD$
.\" Copyright (c) 1997
.\"	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.
.\"
.Dd February 7, 1997
.Dt PCICONF 8
.Os FreeBSD
.Sh NAME
.Nm pciconf
.Nd diagnostic utility for the PCI bus
.Sh SYNOPSIS
.Nm
.Fl l
.Nm
.Fl a Ar selector
.Nm
.Fl r Ar selector
.Op Fl b | Fl h
.Ar reg Ns Op : Ns Ar reg2
.Nm
.Fl w Ar selector
.Op Fl b | Fl h
.Ar reg value
.Sh DESCRIPTION
The
.Nm
command provides a command line interface to the functionality provided by
.Pa /dev/pci Ns 's
.Xr ioctl 2
interface.
With the 
.Fl l
option, it lists all devices found by the boot probe in the following format:
.Bd -literal
foo0@pci0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00
bar0@pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00
none0@pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00
.Ed
.Pp
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.
.Pp
The first column gives the 
device name, unit number, and
.Ar selector .
If there is no device configured in the kernel for the
.Tn PCI
device in question, the device name will be
.Dq none .
Unit numbers for unconfigured devices start at zero and are incremented for
each unconfigured device that is encountered.  The
.Ar 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.
It is 0 for most current (2.0)
.Tn PCI
cards, but is supposed to be loaded with a unique card identification code
in newly developed 
.Tn PCI 
cards.
The field consists of the card ID in the upper
half and the card vendor ID in the lower half of the value.
.Pp
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 are 0 for all devices except 
.Tn PCI
to
.Tn PCI
bridges, and 1 for such bridge chips.
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.
.Pp
The 
.Fl l
option is the only one available to non-root users.
All other invocations of 
.Nm
require a
.Ar selector 
of the form
.Li pci Ns Va bus Ns \&: Ns Va device
(optionally followed by
.Li \&: Ns Va function ) .
A final colon may be appended and
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.
.Pp
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.
.Pp
The 
.Fl r
option reads a configuration space register at byte offset 
.Ar reg 
of device
.Ar selector
and prints out its value in hexadecimal.
The optional second
.Ar reg2
specifies a range to read.
The 
.Fl w 
option writes the 
.Ar value
into a configuration space register at byte offset 
.Ar reg 
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
.Pa /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 kldload 8 
.Sh HISTORY
The 
.Nm
command 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
facility 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 .
.Pp
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.