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 September 30, 2007
  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 cv
  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 c
 116 option is supplied,
 117 .Nm
 118 will list any capabilities supported by each device.
 119 Each capability will be enumerated via a line in the following format:
 120 .Bd -literal
 121     cap 10[40] = PCI-Express 1 root port
 122 .Ed
 123 .Pp
 124 The first value after the
 125 .Dq Li cap
 126 prefix is the capability ID in hexadecimal.
 127 The second value in the square brackets is the offset of the capability
 128 in config space in hexadecimal.
 129 The format of the text after the equals sign is capability-specific.
 130 .Pp
 131 If the
 132 .Fl v
 133 option is supplied,
 134 .Nm
 135 will attempt to load the vendor/device information database, and print
 136 vendor, device, class and subclass identification strings for each device.
 137 .Pp
 138 All invocations of
 139 .Nm
 140 except for
 141 .Fl l
 142 require a
 143 .Ar selector
 144 of the form
 145 .Li pci Ns Va domain Ns \&: Ns Va bus Ns \&: Ns Va device
 146 (optionally followed by
 147 .Li \&: Ns Va function ) .
 148 A final colon may be appended and
 149 will be ignored; this is so that the first column in the output of
 150 .Nm
 151 .Fl l
 152 can be used without modification.
 153 All numbers are base 10.
 154 .Pp
 155 With the
 156 .Fl a
 157 flag,
 158 .Nm
 159 determines whether any driver has been assigned to the device
 160 identified by
 161 .Ar selector .
 162 An exit status of zero indicates that the device has a driver;
 163 non-zero indicates that it does not.
 164 .Pp
 165 The
 166 .Fl r
 167 option reads a configuration space register at byte offset
 168 .Ar addr
 169 of device
 170 .Ar selector
 171 and prints out its value in hexadecimal.
 172 The optional second address
 173 .Ar addr2
 174 specifies a range to read.
 175 The
 176 .Fl w
 177 option writes the
 178 .Ar value
 179 into a configuration space register at byte offset
 180 .Ar addr
 181 of device
 182 .Ar selector .
 183 For both operations, the flags
 184 .Fl b
 185 and
 186 .Fl h
 187 select the width of the operation;
 188 .Fl b
 189 indicates a byte operation, and
 190 .Fl h
 191 indicates a halfword (two-byte) operation.
 192 The default is to read or
 193 write a longword (four bytes).
 194 .Sh ENVIRONMENT
 195 The PCI vendor/device information database is normally read from
 196 .Pa /usr/share/misc/pci_vendors .
 197 This path can be overridden by setting the environment variable
 198 .Ev PCICONF_VENDOR_DATABASE .
 199 .Sh SEE ALSO
 200 .Xr ioctl 2 ,
 201 .\" .Xr pci 4 ,
 202 .Xr kldload 8
 203 .Sh HISTORY
 204 The
 205 .Nm
 206 utility appeared first in
 207 .Fx 2.2 .
 208 The
 209 .Fl a
 210 option was added for
 211 .Tn PCI
 212 KLD support in
 213 .Fx 3.0 .
 214 .Sh AUTHORS
 215 .An -nosplit
 216 The
 217 .Nm
 218 utility was written by
 219 .An Stefan Esser
 220 and
 221 .An Garrett Wollman .
 222 .Sh BUGS
 223 The
 224 .Fl b
 225 and
 226 .Fl h
 227 options are implemented in
 228 .Nm ,
 229 but not in the underlying
 230 .Xr ioctl 2 .
 231 .Pp
 232 It might be useful to give non-root users access to the
 233 .Fl a
 234 and
 235 .Fl r
 236 options.
 237 But only root will be able to execute a
 238 .Nm kldload
 239 to provide the device with a driver KLD, and reading of configuration space
 240 registers may cause a failure in badly designed
 241 .Tn PCI
 242 chips.