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