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