xref: /freebsd/usr.sbin/pciconf/pciconf.8 (revision 730cecb05aaf016ac52ef7cfc691ccec3a0408cd)
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 June 1, 2012
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 bcev
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 b
116option is supplied,
117.Nm
118will list any base address registers
119.Pq BARs
120that are assigned resources for each device.
121Each BAR will be enumerated via a line in the following format:
122.Bd -literal
123    bar   [10] = type Memory, range 32, base 0xda060000, size 131072, enabled
124.Ed
125.Pp
126The first value after the
127.Dq Li bar
128prefix in the square brackets is the offset of the BAR in config space in
129hexadecimal.
130The type of a BAR is one of
131.Dq Memory ,
132.Dq Prefetchable Memory ,
133or
134.Dq I/O Port .
135The range indicates the maximum address the BAR decodes.
136The base and size indicate the start and length of the BAR's address window,
137respectively.
138Finally, the last flag indicates if the BAR is enabled or disabled.
139.Pp
140If the
141.Fl c
142option is supplied,
143.Nm
144will list any capabilities supported by each device.
145Each capability is enumerated via a line in the following format:
146.Bd -literal
147    cap 10[40] = PCI-Express 1 root port
148.Ed
149.Pp
150The first value after the
151.Dq Li cap
152prefix is the capability ID in hexadecimal.
153The second value in the square brackets is the offset of the capability
154in config space in hexadecimal.
155The format of the text after the equals sign is capability-specific.
156.Pp
157Each extended capability is enumerated via a line in a similar format:
158.Bd -literal
159ecap 0002[100] = VC 1 max VC0
160.Ed
161.Pp
162The first value after the
163.Dq Li ecap
164prefix is the extended capability ID in hexadecimal.
165The second value in the square brackets is the offset of the extended
166capability in config space in hexadecimal.
167The format of the text after the equals sign is capability-specific.
168.Pp
169If the
170.Fl e
171option is supplied,
172.Nm
173will list any errors reported for this device in standard PCI error registers.
174Errors are checked for in the PCI status register,
175the PCI-express device status register,
176and the Advanced Error Reporting status registers.
177.Pp
178If the
179.Fl v
180option is supplied,
181.Nm
182will attempt to load the vendor/device information database, and print
183vendor, device, class and subclass identification strings for each device.
184.Pp
185All invocations of
186.Nm
187except for
188.Fl l
189require a
190.Ar selector
191of the form
192.Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \
193Ns Va function Ns ,
194.Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns , or
195.Li pci Ns Va bus Ns \&: Ns Va device Ns .
196In case of an abridged form, omitted selector components are assumed to be 0.
197An optional leading device name followed by @ and an optional final colon
198will be ignored; this is so that the first column in the output of
199.Nm
200.Fl l
201can be used without modification.
202All numbers are base 10.
203.Pp
204With the
205.Fl a
206flag,
207.Nm
208determines whether any driver has been assigned to the device
209identified by
210.Ar selector .
211An exit status of zero indicates that the device has a driver;
212non-zero indicates that it does not.
213.Pp
214The
215.Fl r
216option reads a configuration space register at byte offset
217.Ar addr
218of device
219.Ar selector
220and prints out its value in hexadecimal.
221The optional second address
222.Ar addr2
223specifies a range to read.
224The
225.Fl w
226option writes the
227.Ar value
228into a configuration space register at byte offset
229.Ar addr
230of device
231.Ar selector .
232For both operations, the flags
233.Fl b
234and
235.Fl h
236select the width of the operation;
237.Fl b
238indicates a byte operation, and
239.Fl h
240indicates a halfword (two-byte) operation.
241The default is to read or
242write a longword (four bytes).
243.Sh ENVIRONMENT
244The PCI vendor/device information database is normally read from
245.Pa /usr/share/misc/pci_vendors .
246This path can be overridden by setting the environment variable
247.Ev PCICONF_VENDOR_DATABASE .
248.Sh SEE ALSO
249.Xr ioctl 2 ,
250.\" .Xr pci 4 ,
251.Xr devinfo 8 ,
252.Xr kldload 8
253.Sh HISTORY
254The
255.Nm
256utility appeared first in
257.Fx 2.2 .
258The
259.Fl a
260option was added for
261.Tn PCI
262KLD support in
263.Fx 3.0 .
264.Sh AUTHORS
265.An -nosplit
266The
267.Nm
268utility was written by
269.An Stefan Esser
270and
271.An Garrett Wollman .
272.Sh BUGS
273The
274.Fl b
275and
276.Fl h
277options are implemented in
278.Nm ,
279but not in the underlying
280.Xr ioctl 2 .
281.Pp
282It might be useful to give non-root users access to the
283.Fl a
284and
285.Fl r
286options.
287But only root will be able to execute a
288.Nm kldload
289to provide the device with a driver KLD, and reading of configuration space
290registers may cause a failure in badly designed
291.Tn PCI
292chips.
293