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 January 20, 2014
  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 bcevV 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 .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 card=0x00000000 chip=0x000f1000 rev=0x01 \
  62 hdr=0x00
  63 bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \
  64 hdr=0x00
  65 none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \
  66 hdr=0x00
  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 gives the contents of the subvendorid register, introduced
  82 in revision 2.1 of the
  83 .Tn PCI
  84 standard.
  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.
  88 .Pp
  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
  92 its vendor, as above.
  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,
  96 1 for
  97 .Tn PCI
  98 to
  99 .Tn PCI
 100 bridges, and 2 for
 101 .Tn PCI
 102 to
 103 .Tn CardBus
 104 bridges.
 105 If the most significant bit
 106 of the header type register is set for
 107 function 0 of a
 108 .Tn PCI
 109 device, it is a
 110 .Em multi-function
 111 device, which contains several (similar or independent) functions on
 112 one chip.
 113 .Pp
 114 If the
 115 .Fl b
 116 option is supplied,
 117 .Nm
 118 will list any base address registers
 119 .Pq BARs
 120 that are assigned resources for each device.
 121 Each 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
 126 The first value after the
 127 .Dq Li bar
 128 prefix in the square brackets is the offset of the BAR in config space in
 129 hexadecimal.
 130 The type of a BAR is one of
 131 .Dq Memory ,
 132 .Dq Prefetchable Memory ,
 133 or
 134 .Dq I/O Port .
 135 The range indicates the maximum address the BAR decodes.
 136 The base and size indicate the start and length of the BAR's address window,
 137 respectively.
 138 Finally, the last flag indicates if the BAR is enabled or disabled.
 139 .Pp
 140 If the
 141 .Fl c
 142 option is supplied,
 143 .Nm
 144 will list any capabilities supported by each device.
 145 Each 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
 150 The first value after the
 151 .Dq Li cap
 152 prefix is the capability ID in hexadecimal.
 153 The second value in the square brackets is the offset of the capability
 154 in config space in hexadecimal.
 155 The format of the text after the equals sign is capability-specific.
 156 .Pp
 157 Each extended capability is enumerated via a line in a similar format:
 158 .Bd -literal
 159 ecap 0002[100] = VC 1 max VC0
 160 .Ed
 161 .Pp
 162 The first value after the
 163 .Dq Li ecap
 164 prefix is the extended capability ID in hexadecimal.
 165 The second value in the square brackets is the offset of the extended
 166 capability in config space in hexadecimal.
 167 The format of the text after the equals sign is capability-specific.
 168 .Pp
 169 If the
 170 .Fl e
 171 option is supplied,
 172 .Nm
 173 will list any errors reported for this device in standard PCI error registers.
 174 Errors are checked for in the PCI status register,
 175 the PCI-express device status register,
 176 and the Advanced Error Reporting status registers.
 177 .Pp
 178 If the
 179 .Fl v
 180 option is supplied,
 181 .Nm
 182 will attempt to load the vendor/device information database, and print
 183 vendor, device, class and subclass identification strings for each device.
 184 .Pp
 185 If the
 186 .Fl V
 187 option is supplied,
 188 .Nm
 189 will list any vital product data
 190 .Pq VPD
 191 provided by each device.
 192 Each VPD keyword is enumerated via a line in the following format:
 193 .Bd -literal
 194     VPD ro PN  = '110114640C0     '
 195 .Ed
 196 .Pp
 197 The first string after the
 198 .Dq Li VPD
 199 prefix indicates if the keyword is read-only
 200 .Dq ro
 201 or read-write
 202 .Dq rw .
 203 The second string provides the keyword name.
 204 The text after the the equals sign lists the value of the keyword which is
 205 usually an ASCII string.
 206 .Pp
 207 If the optional
 208 .Ar device
 209 argument is given with the
 210 .Fl l
 211 flag,
 212 .Nm
 213 will only list details about a single device instead of all devices.
 214 .Pp
 215 All invocations of
 216 .Nm
 217 except for
 218 .Fl l
 219 require a
 220 .Ar device .
 221 The device can be identified either by a device name if the device is
 222 attached to a driver or by a selector.
 223 Selectors identify a PCI device by its address in PCI config space and
 224 can take one of the following forms:
 225 .Pp
 226 .Bl -bullet -offset indent -compact
 227 .It
 228 .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \
 229 Ns Va function Ns
 230 .It
 231 .Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function Ns
 232 .It
 233 .Li pci Ns Va bus Ns \&: Ns Va device Ns
 234 .El
 235 .Pp
 236 In the case of an abridged form, omitted selector components are assumed to be 0.
 237 An optional leading device name followed by @ and an optional final colon
 238 will be ignored; this is so that the first column in the output of
 239 .Nm
 240 .Fl l
 241 can be used without modification.
 242 All numbers are base 10.
 243 .Pp
 244 With the
 245 .Fl a
 246 flag,
 247 .Nm
 248 determines whether any driver has been assigned to the device
 249 identified by
 250 .Ar selector .
 251 An exit status of zero indicates that the device has a driver;
 252 non-zero indicates that it does not.
 253 .Pp
 254 The
 255 .Fl r
 256 option reads a configuration space register at byte offset
 257 .Ar addr
 258 of device
 259 .Ar selector
 260 and prints out its value in hexadecimal.
 261 The optional second address
 262 .Ar addr2
 263 specifies a range to read.
 264 The
 265 .Fl w
 266 option writes the
 267 .Ar value
 268 into a configuration space register at byte offset
 269 .Ar addr
 270 of device
 271 .Ar selector .
 272 For both operations, the flags
 273 .Fl b
 274 and
 275 .Fl h
 276 select the width of the operation;
 277 .Fl b
 278 indicates a byte operation, and
 279 .Fl h
 280 indicates a halfword (two-byte) operation.
 281 The default is to read or
 282 write a longword (four bytes).
 283 .Sh ENVIRONMENT
 284 The PCI vendor/device information database is normally read from
 285 .Pa /usr/share/misc/pci_vendors .
 286 This path can be overridden by setting the environment variable
 287 .Ev PCICONF_VENDOR_DATABASE .
 288 .Sh SEE ALSO
 289 .Xr ioctl 2 ,
 290 .\" .Xr pci 4 ,
 291 .Xr devinfo 8 ,
 292 .Xr kldload 8
 293 .Sh HISTORY
 294 The
 295 .Nm
 296 utility appeared first in
 297 .Fx 2.2 .
 298 The
 299 .Fl a
 300 option was added for
 301 .Tn PCI
 302 KLD support in
 303 .Fx 3.0 .
 304 .Sh AUTHORS
 305 .An -nosplit
 306 The
 307 .Nm
 308 utility was written by
 309 .An Stefan Esser
 310 and
 311 .An Garrett Wollman .
 312 .Sh BUGS
 313 The
 314 .Fl b
 315 and
 316 .Fl h
 317 options are implemented in
 318 .Nm ,
 319 but not in the underlying
 320 .Xr ioctl 2 .
 321 .Pp
 322 It might be useful to give non-root users access to the
 323 .Fl a
 324 and
 325 .Fl r
 326 options.
 327 But only root will be able to execute a
 328 .Nm kldload
 329 to provide the device with a driver KLD, and reading of configuration space
 330 registers may cause a failure in badly designed
 331 .Tn PCI
 332 chips.