usr.sbin/pciconf/pciconf.8

   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 .Dd June 14, 2018
  27 .Dt PCICONF 8
  28 .Os
  29 .Sh NAME
  30 .Nm pciconf
  31 .Nd diagnostic utility for the PCI bus
  32 .Sh SYNOPSIS
  33 .Nm
  34 .Fl l Oo Fl BbceVv Oc Op Ar device
  35 .Nm
  36 .Fl a Ar device
  37 .Nm
  38 .Fl r Oo Fl b | h Oc Ar device addr Ns Op : Ns Ar addr2
  39 .Nm
  40 .Fl w Oo Fl b | h Oc Ar device addr value
  41 .Nm
  42 .Fl D Oo Fl b | h | x Oc Ar device addr Op start Ns Op : Ns Ar count
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 utility provides a command line interface to functionality provided by the
  47 .Xr pci 4
  48 .Xr ioctl 2
  49 interface.
  50 As such, some of the functions are only available to users with write
  51 access to
  52 .Pa /dev/pci ,
  53 normally only the super-user.
  54 .Pp
  55 With the
  56 .Fl l
  57 option,
  58 .Nm
  59 lists PCI devices in the following format:
  60 .Bd -literal
  61 foo0@pci0:0:4:0: class=0x010000 rev=0x01 hdr=0x00 vendor=0x1000 device=0x000f \
  62 subvendor=0x0000 subdevice=0x0000
  63 bar0@pci0:0:5:0: class=0x000100 rev=0x00 hdr=0x00 vendor=0x88c1 device=0x5333 \
  64 subvendor=0x0000 subdevice=0x0000
  65 none0@pci0:0:6:0: class=0x020000 rev=0x00 hdr=0x00 vendor=0x10ec device=0x8029 \
  66 subvendor=0x0000 subdevice=0x0000
  67 .Ed
  68 .Pp
  69 The first column gives the
  70 driver name, unit number, and selector.
  71 If there is no driver attached to the
  72 .Tn PCI
  73 device in question, the driver name will be
  74 .Dq none .
  75 Unit numbers for detached devices start at zero and are incremented for
  76 each detached device that is encountered.
  77 The selector
  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 prints the device's revision.
  82 The fourth column describes the header type.
  83 .Pp
  84 Currently assigned header types include 0 for standard devices,
  85 1 for
  86 .Tn PCI
  87 to
  88 .Tn PCI
  89 bridges, and 2 for
  90 .Tn PCI
  91 to
  92 .Tn CardBus
  93 bridges.
  94 If the most significant bit
  95 of the header type register is set for
  96 function 0 of a
  97 .Tn PCI
  98 device, it is a
  99 .Em multi-function
 100 device, which contains several (similar or independent) functions on
 101 one chip.
 102 .Pp
 103 The sixth and seventh columns contain the vendor ID and the device ID of the
 104 device.
 105 The eigth and ninth columns contain subvendor and subdevice IDs, introduced
 106 in revision 2.1 of the
 107 .Tn PCI
 108 standard.
 109 Note that they will be 0 for older cards.
 110 .Pp
 111 Adding a second
 112 .Fl l
 113 option causes output to be in a compact columnar format, suitable for
 114 80 column output:
 115 .Bd -literal
 116 drv     selector        class   rev hdr vendor device subven subdev
 117 foo0@pci0:0:4:0:        010000  01  00  1000   000f   0000   0000
 118 bar0@pci0:0:5:0:        000100  00  00  88c1   5333   0000   0000
 119 none0@pci0:0:6:0:       020000  00  00  10ec   8029   0000   0000
 120 .Ed
 121 .Pp
 122 All fields retain the same definition as with the non-compact form.
 123 .Pp
 124 If the
 125 .Fl B
 126 option is supplied,
 127 .Nm
 128 will list additional information for
 129 .Tn PCI
 130 to
 131 .Tn PCI
 132 and
 133 .Tn PCI
 134 to
 135 .Tn CardBus
 136 bridges,
 137 specifically the resource ranges decoded by the bridge for use by devices
 138 behind the bridge.
 139 Each bridge lists a range of bus numbers handled by the bridge and its
 140 downstream devices.
 141 Memory and I/O port decoding windows are enumerated via a line in the
 142 following format:
 143 .Bd -literal
 144     window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled
 145 .Ed
 146 .Pp
 147 The first value after the
 148 .Dq Li window
 149 prefix in the square brackets is the offset of the decoding window in
 150 config space in hexadecimal.
 151 The type of a window is one of
 152 .Dq Memory ,
 153 .Dq Prefetchable Memory ,
 154 or
 155 .Dq I/O Port .
 156 The range indicates the binary log of the maximum address the window decodes.
 157 The address field indicates the start and end addresses of the decoded range.
 158 Finally, the last flag indicates if the window is enabled or disabled.
 159 .Pp
 160 If the
 161 .Fl b
 162 option is supplied,
 163 .Nm
 164 will list any base address registers
 165 .Pq BARs
 166 that are assigned resources for each device.
 167 Each BAR will be enumerated via a line in the following format:
 168 .Bd -literal
 169     bar   [10] = type Memory, range 32, base 0xda060000, size 131072, enabled
 170 .Ed
 171 .Pp
 172 The first value after the
 173 .Dq Li bar
 174 prefix in the square brackets is the offset of the BAR in config space in
 175 hexadecimal.
 176 The type of a BAR is one of
 177 .Dq Memory ,
 178 .Dq Prefetchable Memory ,
 179 or
 180 .Dq I/O Port .
 181 The range indicates the binary log of the maximum address the BAR decodes.
 182 The base and size indicate the start and length of the BAR's address window,
 183 respectively.
 184 Finally, the last flag indicates if the BAR is enabled or disabled.
 185 .Pp
 186 If the
 187 .Fl c
 188 option is supplied,
 189 .Nm
 190 will list any capabilities supported by each device.
 191 A second invocation of
 192 .Fl c
 193 will print additional data for certain capabilities.
 194 Each capability is enumerated via a line in the following format:
 195 .Bd -literal
 196     cap 10[40] = PCI-Express 1 root port
 197 .Ed
 198 .Pp
 199 The first value after the
 200 .Dq Li cap
 201 prefix is the capability ID in hexadecimal.
 202 The second value in the square brackets is the offset of the capability
 203 in config space in hexadecimal.
 204 The format of the text after the equals sign is capability-specific.
 205 .Pp
 206 Each extended capability is enumerated via a line in a similar format:
 207 .Bd -literal
 208 ecap 0002[100] = VC 1 max VC0
 209 .Ed
 210 .Pp
 211 The first value after the
 212 .Dq Li ecap
 213 prefix is the extended capability ID in hexadecimal.
 214 The second value in the square brackets is the offset of the extended
 215 capability in config space in hexadecimal.
 216 The format of the text after the equals sign is capability-specific.
 217 .Pp
 218 If the
 219 .Fl e
 220 option is supplied,
 221 .Nm
 222 will list any errors reported for this device in standard PCI error registers.
 223 Errors are checked for in the PCI status register,
 224 the PCI-express device status register,
 225 and the Advanced Error Reporting status registers.
 226 .Pp
 227 If the
 228 .Fl v
 229 option is supplied,
 230 .Nm
 231 will attempt to load the vendor/device information database, and print
 232 vendor, device, class and subclass identification strings for each device.
 233 .Pp
 234 If the
 235 .Fl V
 236 option is supplied,
 237 .Nm
 238 will list any vital product data
 239 .Pq VPD
 240 provided by each device.
 241 Each VPD keyword is enumerated via a line in the following format:
 242 .Bd -literal
 243     VPD ro PN  = '110114640C0     '
 244 .Ed
 245 .Pp
 246 The first string after the
 247 .Dq Li VPD
 248 prefix indicates if the keyword is read-only
 249 .Dq ro
 250 or read-write
 251 .Dq rw .
 252 The second string provides the keyword name.
 253 The text after the equals sign lists the value of the keyword which is
 254 usually an ASCII string.
 255 .Pp
 256 If the optional
 257 .Ar device
 258 argument is given with the
 259 .Fl l
 260 flag,
 261 .Nm
 262 will only list details about a single device instead of all devices.
 263 .Pp
 264 All invocations of
 265 .Nm
 266 except for
 267 .Fl l
 268 require a
 269 .Ar device .
 270 The device can be identified either by a device name if the device is
 271 attached to a driver or by a selector.
 272 Selectors identify a PCI device by its address in PCI config space and
 273 can take one of the following forms:
 274 .Pp
 275 .Bl -bullet -offset indent -compact
 276 .It
 277 .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \
 278 Ns Va function Ns
 279 .It
 280 .Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns
 281 .It
 282 .Li pci Ns Va bus Ns \&: Ns Va device Ns
 283 .El
 284 .Pp
 285 In the case of an abridged form, omitted selector components are assumed to be 0.
 286 An optional leading device name followed by @ and an optional final colon
 287 will be ignored; this is so that the first column in the output of
 288 .Nm
 289 .Fl l
 290 can be used without modification.
 291 All numbers are base 10.
 292 .Pp
 293 With the
 294 .Fl a
 295 flag,
 296 .Nm
 297 determines whether any driver has been assigned to the device
 298 identified by
 299 .Ar selector .
 300 An exit status of zero indicates that the device has a driver;
 301 non-zero indicates that it does not.
 302 .Pp
 303 The
 304 .Fl r
 305 option reads a configuration space register at byte offset
 306 .Ar addr
 307 of device
 308 .Ar selector
 309 and prints out its value in hexadecimal.
 310 The optional second address
 311 .Ar addr2
 312 specifies a range to read.
 313 The
 314 .Fl w
 315 option writes the
 316 .Ar value
 317 into a configuration space register at byte offset
 318 .Ar addr
 319 of device
 320 .Ar selector .
 321 .Pp
 322 The
 323 .Fl D
 324 option request a dump of the specified BAR.
 325 Dump is performed to the standard output, raw register values
 326 are written.
 327 Use
 328 .Xr hexdump 1
 329 to convert them to human-readable dump,
 330 or redirect into a file to save the snapshot of the device state.
 331 Optionally, the
 332 .Ar start
 333 and
 334 .Ar count
 335 of the registers dumped can be specified, in multiple of the operation width,
 336 see next paragraph.
 337 .Pp
 338 For read, write, and dump operations, the flags
 339 .Fl b ,
 340 .Fl h ,
 341 and
 342 .Fl x
 343 select the width of the operation;
 344 .Fl b
 345 indicates a byte operation, and
 346 .Fl h
 347 indicates a halfword (two-byte) operation.
 348 .Fl x
 349 indicates a quadword (four-byte) operation.
 350 The default is to read or
 351 write a longword (four bytes).
 352 The quadword mode is only valid for BAR dump.
 353 .Sh ENVIRONMENT
 354 PCI vendor and device information is read from
 355 .Pa /usr/local/share/pciids/pci.ids .
 356 If that file is not present, it is read from
 357 .Pa /usr/share/misc/pci_vendors .
 358 This path can be overridden by setting the environment variable
 359 .Ev PCICONF_VENDOR_DATABASE .
 360 .Sh SEE ALSO
 361 .Xr ioctl 2 ,
 362 .\" .Xr pci 4 ,
 363 .Xr devinfo 8 ,
 364 .Xr kldload 8
 365 .Sh HISTORY
 366 The
 367 .Nm
 368 utility appeared first in
 369 .Fx 2.2 .
 370 The
 371 .Fl a
 372 option was added for
 373 .Tn PCI
 374 KLD support in
 375 .Fx 3.0 .
 376 .Sh AUTHORS
 377 .An -nosplit
 378 The
 379 .Nm
 380 utility was written by
 381 .An Stefan Esser
 382 and
 383 .An Garrett Wollman .
 384 .Sh BUGS
 385 The
 386 .Fl b
 387 and
 388 .Fl h
 389 options are implemented in
 390 .Nm ,
 391 but not in the underlying
 392 .Xr ioctl 2 .
 393 .Pp
 394 It might be useful to give non-root users access to the
 395 .Fl a
 396 and
 397 .Fl r
 398 options.
 399 But only root will be able to execute a
 400 .Nm kldload
 401 to provide the device with a driver KLD, and reading of configuration space
 402 registers may cause a failure in badly designed
 403 .Tn PCI
 404 chips.
 405 .Pp
 406 There is currently no way to specify the caching mode for the mapping
 407 established by the
 408 .Fl D
 409 option,
 410 .Nm
 411 always uses uncached access.
 412 This is fine for control register BARs.