The devinfo(3) library provides userspace access to the internal device
[dragonfly.git] / usr.sbin / pciconf / pciconf.8
CommitLineData
984263bc 1.\" $FreeBSD: src/usr.sbin/pciconf/pciconf.8,v 1.8.2.9 2003/03/11 22:31:30 trhodes Exp $
0010e23a 2.\" $DragonFly: src/usr.sbin/pciconf/pciconf.8,v 1.4 2008/09/30 12:20:29 hasso Exp $
984263bc
MD
3.\" Copyright (c) 1997
4.\" Stefan Esser <se@FreeBSD.org>. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\"
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.Dd February 7, 1997
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 v
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, it is only available to users with write access to
51.Pa /dev/pci ,
52normally only the super-user.
53.Pp
54With the
55.Fl l
56option, it lists all devices found by the boot probe in the following format:
57.Bd -literal
58foo0@pci0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00
59bar0@pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00
60none0@pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00
61.Ed
62.Pp
63If the
64.Fl v
65option is supplied,
66.Nm
67will attempt to load the vendor/device information database, and print
68vendor, device, class and subclass identification strings for each device.
69.Pp
70The first column gives the
71device name, unit number, and
72.Ar selector .
73If there is no device configured in the kernel for the
74.Tn PCI
75device in question, the device name will be
76.Dq none .
77Unit numbers for unconfigured devices start at zero and are incremented for
78each unconfigured device that is encountered.
79The
80.Ar selector
81is in a form which may directly be used for the other forms of the command.
82The second column is the class code, with the class byte printed as two
83hex digits, followed by the sub-class and the interface bytes.
84The third column gives the contents of the subvendorid register, introduced
85in revision 2.1 of the
86.Tn PCI
87standard.
88It is 0 for most current (2.0)
89.Tn PCI
90cards, but is supposed to be loaded with a unique card identification code
91in newly developed
92.Tn PCI
93cards.
94The field consists of the card ID in the upper
95half and the card vendor ID in the lower half of the value.
96.Pp
97The fourth column contains the chip device ID, which identifies the chip
98this card is based on.
99It consists of two fields, identifying the chip and
100its vendor, as above.
101The fifth column prints the chip's revision.
102The sixth column describes the header type.
103Currently assigned header types are 0 for all devices except
104.Tn PCI
105to
106.Tn PCI
107bridges, and 1 for such bridge chips.
108If the most significant bit
109of the header type register is set for
110function 0 of a
111.Tn PCI
112device, it is a
113.Em multi-function
114device, which contains several (similar or independent) functions on
115one chip.
116.Pp
117All invocations of
118.Nm
119except for
120.Fl l
121require a
122.Ar selector
123of the form
124.Li pci Ns Va bus Ns \&: Ns Va device
125(optionally followed by
126.Li \&: Ns Va function ) .
127A final colon may be appended and
128will be ignored; this is so that the first column in the output of
129.Nm
130.Fl l
131can be used without modification.
132All numbers are base 10.
133.Pp
134With the
135.Fl a
136flag,
137.Nm
138determines whether any driver has been assigned to the device
139identified by
140.Ar selector .
141An exit status of zero indicates that the device has a driver;
142non-zero indicates that it does not.
143.Pp
144The
145.Fl r
146option reads a configuration space register at byte offset
147.Ar addr
148of device
149.Ar selector
150and prints out its value in hexadecimal.
151The optional second address
152.Ar addr2
153specifies a range to read.
154The
155.Fl w
156option writes the
157.Ar value
158into a configuration space register at byte offset
159.Ar addr
160of device
161.Ar selector .
162For both operations, the flags
163.Fl b
164and
165.Fl h
166select the width of the operation;
167.Fl b
168indicates a byte operation, and
169.Fl h
170indicates a halfword (two-byte) operation.
171The default is to read or
172write a longword (four bytes).
173.Sh ENVIRONMENT
174The PCI vendor/device information database is normally read from
175.Pa /usr/share/misc/pci_vendors .
176This path can be overridden by setting the environment variable
177.Ev PCICONF_VENDOR_DATABASE .
178.Sh SEE ALSO
179.Xr ioctl 2 ,
ad7abf4a 180.Xr pci 4 ,
0010e23a 181.Xr devinfo 8 ,
984263bc
MD
182.Xr kldload 8
183.Sh HISTORY
184The
185.Nm
186utility appeared first in
187.Fx 2.2 .
188The
189.Fl a
190option was added for
191.Tn PCI
192KLD support in
193.Fx 3.0 .
194.Sh AUTHORS
195.An -nosplit
196The
197.Nm
198utility was written by
199.An Stefan Esser
200and
201.An Garrett Wollman .
202.Sh BUGS
203The
204.Fl b
205and
206.Fl h
207options are implemented in
208.Nm ,
209but not in the underlying
210.Xr ioctl 2 .
211.Pp
212It might be useful to give non-root users access to the
213.Fl a
214and
215.Fl r
216options.
217But only root will be able to execute a
218.Nm kldload
219to provide the device with a driver KLD, and reading of configuration space
220registers may cause a failure in badly designed
221.Tn PCI
222chips.