2 .\" Stefan Esser <se@FreeBSD.org>. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
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.
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
33 .Nd diagnostic utility for the PCI bus
36 .Fl l Oo Fl BbceVv Oc Op Ar device
40 .Fl r Oo Fl b | h Oc Ar device addr Ns Op : Ns Ar addr2
42 .Fl w Oo Fl b | h Oc Ar device addr value
46 utility provides a command line interface to functionality provided by the
50 As such, some of the functions are only available to users with write
53 normally only the super-user.
59 lists PCI devices in the following format:
61 foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \
63 bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \
65 none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \
69 The first column gives the
70 driver name, unit number, and selector .
71 If there is no driver attached to the
73 device in question, the driver name will be
75 Unit numbers for detached devices start at zero and are incremented for
76 each detached device that is encountered.
78 is in a form which may directly be used for the other forms of the command.
79 The second column is the class code, with the class byte printed as two
80 hex digits, followed by the sub-class and the interface bytes.
81 The third column gives the contents of the subvendorid register, introduced
82 in revision 2.1 of the
85 Note that it will be 0 for older cards.
86 The field consists of the card ID in the upper
87 half and the card vendor ID in the lower half of the value.
89 The fourth column contains the chip device ID, which identifies the chip
90 this card is based on.
91 It consists of two fields, identifying the chip and
93 The fifth column prints the chip's revision.
94 The sixth column describes the header type.
95 Currently assigned header types include 0 for most devices,
105 If the most significant bit
106 of the header type register is set for
111 device, which contains several (similar or independent) functions on
118 will list additional information for
127 specifically the resource ranges decoded by the bridge for use by devices
129 Each bridge lists a range of bus numbers handled by the bridge and its
131 Memory and I/O port decoding windows are enumerated via a line in the
134 window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled
137 The first value after the
139 prefix in the square brackets is the offset of the decoding window in
140 config space in hexadecimal.
141 The type of a window is one of
143 .Dq Prefetchable Memory ,
146 The range indicates the binary log of the maximum address the window decodes.
147 The address field indicates the start and end addresses of the decoded range.
148 Finally, the last flag indicates if the window is enabled or disabled.
154 will list any base address registers
156 that are assigned resources for each device.
157 Each BAR will be enumerated via a line in the following format:
159 bar [10] = type Memory, range 32, base 0xda060000, size 131072, enabled
162 The first value after the
164 prefix in the square brackets is the offset of the BAR in config space in
166 The type of a BAR is one of
168 .Dq Prefetchable Memory ,
171 The range indicates the binary log of the maximum address the BAR decodes.
172 The base and size indicate the start and length of the BAR's address window,
174 Finally, the last flag indicates if the BAR is enabled or disabled.
180 will list any capabilities supported by each device.
181 Each capability is enumerated via a line in the following format:
183 cap 10[40] = PCI-Express 1 root port
186 The first value after the
188 prefix is the capability ID in hexadecimal.
189 The second value in the square brackets is the offset of the capability
190 in config space in hexadecimal.
191 The format of the text after the equals sign is capability-specific.
193 Each extended capability is enumerated via a line in a similar format:
195 ecap 0002[100] = VC 1 max VC0
198 The first value after the
200 prefix is the extended capability ID in hexadecimal.
201 The second value in the square brackets is the offset of the extended
202 capability in config space in hexadecimal.
203 The format of the text after the equals sign is capability-specific.
209 will list any errors reported for this device in standard PCI error registers.
210 Errors are checked for in the PCI status register,
211 the PCI-express device status register,
212 and the Advanced Error Reporting status registers.
218 will attempt to load the vendor/device information database, and print
219 vendor, device, class and subclass identification strings for each device.
225 will list any vital product data
227 provided by each device.
228 Each VPD keyword is enumerated via a line in the following format:
230 VPD ro PN = '110114640C0 '
233 The first string after the
235 prefix indicates if the keyword is read-only
239 The second string provides the keyword name.
240 The text after the equals sign lists the value of the keyword which is
241 usually an ASCII string.
245 argument is given with the
249 will only list details about a single device instead of all devices.
257 The device can be identified either by a device name if the device is
258 attached to a driver or by a selector.
259 Selectors identify a PCI device by its address in PCI config space and
260 can take one of the following forms:
262 .Bl -bullet -offset indent -compact
264 .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \
267 .Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns
269 .Li pci Ns Va bus Ns \&: Ns Va device Ns
272 In the case of an abridged form, omitted selector components are assumed to be 0.
273 An optional leading device name followed by @ and an optional final colon
274 will be ignored; this is so that the first column in the output of
277 can be used without modification.
278 All numbers are base 10.
284 determines whether any driver has been assigned to the device
287 An exit status of zero indicates that the device has a driver;
288 non-zero indicates that it does not.
292 option reads a configuration space register at byte offset
296 and prints out its value in hexadecimal.
297 The optional second address
299 specifies a range to read.
304 into a configuration space register at byte offset
308 For both operations, the flags
312 select the width of the operation;
314 indicates a byte operation, and
316 indicates a halfword (two-byte) operation.
317 The default is to read or
318 write a longword (four bytes).
320 PCI vendor and device information is read from
321 .Pa /usr/local/share/pciids/pci.ids .
322 If that file is not present, it is read from
323 .Pa /usr/share/misc/pci_vendors .
324 This path can be overridden by setting the environment variable
325 .Ev PCICONF_VENDOR_DATABASE .
334 utility appeared first in
346 utility was written by
349 .An Garrett Wollman .
355 options are implemented in
357 but not in the underlying
360 It might be useful to give non-root users access to the
365 But only root will be able to execute a
367 to provide the device with a driver KLD, and reading of configuration space
368 registers may cause a failure in badly designed