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: src/usr.sbin/pciconf/pciconf.8,v 1.34 2010/09/09 18:51:20 jhb Exp $
  27 .\"
  28 .Dd March 21, 2021
  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 Op Fl Bbcev
  37 .Nm
  38 .Fl a Ar selector
  39 .Nm
  40 .Fl r Oo Fl b | h Oc Ar selector addr Ns Op : Ns Ar addr2
  41 .Nm
  42 .Fl w Oo Fl b | h Oc Ar selector 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, it lists all devices found by the boot probe in the following format:
  58 .Bd -literal
  59 foo0@pci0:0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 \
  60 hdr=0x00
  61 bar0@pci0:0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 \
  62 hdr=0x00
  63 none0@pci0:0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 \
  64 hdr=0x00
  65 .Ed
  66 .Pp
  67 The first column gives the
  68 device name, unit number, and
  69 .Ar selector .
  70 If there is no device configured in the kernel for the
  71 .Tn PCI
  72 device in question, the device name will be
  73 .Dq none .
  74 Unit numbers for unconfigured devices start at zero and are incremented for
  75 each unconfigured device that is encountered.
  76 The
  77 .Ar 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 additional information for
 119 .Tn PCI
 120 to
 121 .Tn PCI
 122 and
 123 .Tn PCI
 124 to
 125 .Tn CardBus
 126 bridges,
 127 specifically the resource ranges decoded by the bridge for use by devices
 128 behind the bridge.
 129 Each bridge lists a range of bus numbers handled by the bridge and its
 130 downstream devices.
 131 Memory and I/O port decoding windows are enumerated via a line in the
 132 following format:
 133 .Bd -literal
 134     window[1c] = type I/O Port, range 16, addr 0x5000-0x8fff, enabled
 135 .Ed
 136 .Pp
 137 The first value after the
 138 .Dq Li window
 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
 142 .Dq Memory ,
 143 .Dq Prefetchable Memory ,
 144 or
 145 .Dq I/O Port .
 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.
 149 .Pp
 150 If the
 151 .Fl b
 152 option is supplied,
 153 .Nm
 154 will list any base address registers
 155 .Pq BARs
 156 that are assigned resources for each device.
 157 Each BAR will be enumerated via a line in the following format:
 158 .Bd -literal
 159     bar   [10] = type Memory, range 32, base 0xda060000, size 131072, enabled
 160 .Ed
 161 .Pp
 162 The first value after the
 163 .Dq Li bar
 164 prefix in the square brackets is the offset of the BAR in config space in
 165 hexadecimal.
 166 The type of a BAR is one of
 167 .Dq Memory ,
 168 .Dq Prefetchable Memory ,
 169 or
 170 .Dq I/O Port .
 171 The range indicates the maximum address the BAR decodes.
 172 The base and size indicate the start and length of the BAR's address window,
 173 respectively.
 174 Finally, the last flag indicates if the BAR is enabled or disabled.
 175 .Pp
 176 If the
 177 .Fl c
 178 option is supplied,
 179 .Nm
 180 will list any capabilities supported by each device.
 181 Each capability is enumerated via a line in the following format:
 182 .Bd -literal
 183     cap 10[40] = PCI-Express 1 root port
 184 .Ed
 185 .Pp
 186 The first value after the
 187 .Dq Li cap
 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.
 192 .Pp
 193 Each extended capability is enumerated via a line in a similar format:
 194 .Bd -literal
 195 ecap 0002[100] = VC 1 max VC0
 196 .Ed
 197 .Pp
 198 The first value after the
 199 .Dq Li ecap
 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.
 204 .Pp
 205 If the
 206 .Fl e
 207 option is supplied,
 208 .Nm
 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.
 213 .Pp
 214 If the
 215 .Fl v
 216 option is supplied,
 217 .Nm
 218 will attempt to load the vendor/device information database, and print
 219 vendor, device, class and subclass identification strings for each device.
 220 .Pp
 221 All invocations of
 222 .Nm
 223 except for
 224 .Fl l
 225 require a
 226 .Ar selector
 227 of the form
 228 .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device Ns \&: \
 229 Ns Va function ,
 230 .Li pci Ns Va bus Ns \&: Ns Va device Ns \&: Ns Va function , or
 231 .Li pci Ns Va bus Ns \&: Ns Va device .
 232 In case of an abridged form, omitted selector components are assumed to be 0.
 233 An optional leading device name followed by @ and an optional final colon
 234 will be ignored; this is so that the first column in the output of
 235 .Nm
 236 .Fl l
 237 can be used without modification.
 238 All numbers are base 10.
 239 .Pp
 240 With the
 241 .Fl a
 242 flag,
 243 .Nm
 244 determines whether any driver has been assigned to the device
 245 identified by
 246 .Ar selector .
 247 An exit status of zero indicates that the device has a driver;
 248 non-zero indicates that it does not.
 249 .Pp
 250 The
 251 .Fl r
 252 option reads a configuration space register at byte offset
 253 .Ar addr
 254 of device
 255 .Ar selector
 256 and prints out its value in hexadecimal.
 257 The optional second address
 258 .Ar addr2
 259 specifies a range to read.
 260 The
 261 .Fl w
 262 option writes the
 263 .Ar value
 264 into a configuration space register at byte offset
 265 .Ar addr
 266 of device
 267 .Ar selector .
 268 For both operations, the flags
 269 .Fl b
 270 and
 271 .Fl h
 272 select the width of the operation;
 273 .Fl b
 274 indicates a byte operation, and
 275 .Fl h
 276 indicates a halfword (two-byte) operation.
 277 The default is to read or
 278 write a longword (four bytes).
 279 .Sh ENVIRONMENT
 280 The PCI vendor/device information database is normally read from
 281 .Pa /usr/share/misc/pci_vendors .
 282 This path can be overridden by setting the environment variable
 283 .Ev PCICONF_VENDOR_DATABASE .
 284 .Sh SEE ALSO
 285 .Xr ioctl 2 ,
 286 .Xr pci 4 ,
 287 .Xr devinfo 8 ,
 288 .Xr kldload 8
 289 .Sh HISTORY
 290 The
 291 .Nm
 292 utility appeared first in
 293 .Fx 2.2 .
 294 The
 295 .Fl a
 296 option was added for
 297 .Tn PCI
 298 KLD support in
 299 .Fx 3.0 .
 300 .Sh AUTHORS
 301 .An -nosplit
 302 The
 303 .Nm
 304 utility was written by
 305 .An Stefan Esser
 306 and
 307 .An Garrett Wollman .
 308 .Sh BUGS
 309 The
 310 .Fl b
 311 and
 312 .Fl h
 313 options are implemented in
 314 .Nm ,
 315 but not in the underlying
 316 .Xr ioctl 2 .
 317 .Pp
 318 It might be useful to give non-root users access to the
 319 .Fl a
 320 and
 321 .Fl r
 322 options.
 323 But only root will be able to execute a
 324 .Nm kldload
 325 to provide the device with a driver KLD, and reading of configuration space
 326 registers may cause a failure in badly designed
 327 .Tn PCI
 328 chips.