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 February 2, 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:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00
  60 bar0@pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00
  61 none0@pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00
  62 .Ed
  63 .Pp
  64 The first column gives the
  65 device name, unit number, and
  66 .Ar selector .
  67 If there is no device configured in the kernel for the
  68 .Tn PCI
  69 device in question, the device name will be
  70 .Dq none .
  71 Unit numbers for unconfigured devices start at zero and are incremented for
  72 each unconfigured device that is encountered.
  73 The
  74 .Ar selector
  75 is in a form which may directly be used for the other forms of the command.
  76 The second column is the class code, with the class byte printed as two
  77 hex digits, followed by the sub-class and the interface bytes.
  78 The third column gives the contents of the subvendorid register, introduced
  79 in revision 2.1 of the
  80 .Tn PCI
  81 standard.
  82 Note that it will be 0 for older cards.
  83 The field consists of the card ID in the upper
  84 half and the card vendor ID in the lower half of the value.
  85 .Pp
  86 The fourth column contains the chip device ID, which identifies the chip
  87 this card is based on.
  88 It consists of two fields, identifying the chip and
  89 its vendor, as above.
  90 The fifth column prints the chip's revision.
  91 The sixth column describes the header type.
  92 Currently assigned header types include 0 for most devices,
  93 1 for
  94 .Tn PCI
  95 to
  96 .Tn PCI
  97 bridges, and 2 for
  98 .Tn PCI
  99 to
 100 .Tn CardBus
 101 bridges.
 102 If the most significant bit
 103 of the header type register is set for
 104 function 0 of a
 105 .Tn PCI
 106 device, it is a
 107 .Em multi-function
 108 device, which contains several (similar or independent) functions on
 109 one chip.
 110 .Pp
 111 If the
 112 .Fl c
 113 option is supplied,
 114 .Nm
 115 will list any capabilities supported by each device.
 116 Each capability will be enumerated via a line in the following format:
 117 .Bd -literal
 118     cap 10[40] = PCI-Express 1 root port
 119 .Ed
 120 .Pp
 121 The first value after the
 122 .Dq Li cap
 123 prefix is the capability ID in hexadecimal.
 124 The second value in the square brackets is the offset of the capability
 125 in config space in hexadecimal.
 126 The format of the text after the equals sign is capability-specific.
 127 .Pp
 128 If the
 129 .Fl v
 130 option is supplied,
 131 .Nm
 132 will attempt to load the vendor/device information database, and print
 133 vendor, device, class and subclass identification strings for each device.
 134 .Pp
 135 All invocations of
 136 .Nm
 137 except for
 138 .Fl l
 139 require a
 140 .Ar selector
 141 of the form
 142 .Li pci Ns Va bus Ns \&: Ns Va device
 143 (optionally followed by
 144 .Li \&: Ns Va function ) .
 145 A final colon may be appended and
 146 will be ignored; this is so that the first column in the output of
 147 .Nm
 148 .Fl l
 149 can be used without modification.
 150 All numbers are base 10.
 151 .Pp
 152 With the
 153 .Fl a
 154 flag,
 155 .Nm
 156 determines whether any driver has been assigned to the device
 157 identified by
 158 .Ar selector .
 159 An exit status of zero indicates that the device has a driver;
 160 non-zero indicates that it does not.
 161 .Pp
 162 The
 163 .Fl r
 164 option reads a configuration space register at byte offset
 165 .Ar addr
 166 of device
 167 .Ar selector
 168 and prints out its value in hexadecimal.
 169 The optional second address
 170 .Ar addr2
 171 specifies a range to read.
 172 The
 173 .Fl w
 174 option writes the
 175 .Ar value
 176 into a configuration space register at byte offset
 177 .Ar addr
 178 of device
 179 .Ar selector .
 180 For both operations, the flags
 181 .Fl b
 182 and
 183 .Fl h
 184 select the width of the operation;
 185 .Fl b
 186 indicates a byte operation, and
 187 .Fl h
 188 indicates a halfword (two-byte) operation.
 189 The default is to read or
 190 write a longword (four bytes).
 191 .Sh ENVIRONMENT
 192 The PCI vendor/device information database is normally read from
 193 .Pa /usr/share/misc/pci_vendors .
 194 This path can be overridden by setting the environment variable
 195 .Ev PCICONF_VENDOR_DATABASE .
 196 .Sh SEE ALSO
 197 .Xr ioctl 2 ,
 198 .\" .Xr pci 4 ,
 199 .Xr kldload 8
 200 .Sh HISTORY
 201 The
 202 .Nm
 203 utility appeared first in
 204 .Fx 2.2 .
 205 The
 206 .Fl a
 207 option was added for
 208 .Tn PCI
 209 KLD support in
 210 .Fx 3.0 .
 211 .Sh AUTHORS
 212 .An -nosplit
 213 The
 214 .Nm
 215 utility was written by
 216 .An Stefan Esser
 217 and
 218 .An Garrett Wollman .
 219 .Sh BUGS
 220 The
 221 .Fl b
 222 and
 223 .Fl h
 224 options are implemented in
 225 .Nm ,
 226 but not in the underlying
 227 .Xr ioctl 2 .
 228 .Pp
 229 It might be useful to give non-root users access to the
 230 .Fl a
 231 and
 232 .Fl r
 233 options.
 234 But only root will be able to execute a
 235 .Nm kldload
 236 to provide the device with a driver KLD, and reading of configuration space
 237 registers may cause a failure in badly designed
 238 .Tn PCI
 239 chips.