usr.sbin/pciconf/pciconf.8

   1 .\" $FreeBSD: src/usr.sbin/pciconf/pciconf.8,v 1.8.2.9 2003/03/11 22:31:30 trhodes Exp $
   2 .\" $DragonFly: src/usr.sbin/pciconf/pciconf.8,v 1.3 2008/07/23 14:14:44 swildner Exp $
   3 .\" Copyright (c) 1997
   4 .\"     Stefan Esser <se@FreeBSD.org>. All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\"
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd February 7, 1997
  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 v
  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, it is only available to users with write access to
  51 .Pa /dev/pci ,
  52 normally only the super-user.
  53 .Pp
  54 With the
  55 .Fl l
  56 option, it lists all devices found by the boot probe in the following format:
  57 .Bd -literal
  58 foo0@pci0:4:0: class=0x010000 card=0x00000000 chip=0x000f1000 rev=0x01 hdr=0x00
  59 bar0@pci0:5:0: class=0x000100 card=0x00000000 chip=0x88c15333 rev=0x00 hdr=0x00
  60 none0@pci0:6:0: class=0x020000 card=0x00000000 chip=0x802910ec rev=0x00 hdr=0x00
  61 .Ed
  62 .Pp
  63 If the
  64 .Fl v
  65 option is supplied,
  66 .Nm
  67 will attempt to load the vendor/device information database, and print
  68 vendor, device, class and subclass identification strings for each device.
  69 .Pp
  70 The first column gives the
  71 device name, unit number, and
  72 .Ar selector .
  73 If there is no device configured in the kernel for the
  74 .Tn PCI
  75 device in question, the device name will be
  76 .Dq none .
  77 Unit numbers for unconfigured devices start at zero and are incremented for
  78 each unconfigured device that is encountered.
  79 The
  80 .Ar selector
  81 is in a form which may directly be used for the other forms of the command.
  82 The second column is the class code, with the class byte printed as two
  83 hex digits, followed by the sub-class and the interface bytes.
  84 The third column gives the contents of the subvendorid register, introduced
  85 in revision 2.1 of the
  86 .Tn PCI
  87 standard.
  88 It is 0 for most current (2.0)
  89 .Tn PCI
  90 cards, but is supposed to be loaded with a unique card identification code
  91 in newly developed
  92 .Tn PCI
  93 cards.
  94 The field consists of the card ID in the upper
  95 half and the card vendor ID in the lower half of the value.
  96 .Pp
  97 The fourth column contains the chip device ID, which identifies the chip
  98 this card is based on.
  99 It consists of two fields, identifying the chip and
 100 its vendor, as above.
 101 The fifth column prints the chip's revision.
 102 The sixth column describes the header type.
 103 Currently assigned header types are 0 for all devices except
 104 .Tn PCI
 105 to
 106 .Tn PCI
 107 bridges, and 1 for such bridge chips.
 108 If the most significant bit
 109 of the header type register is set for
 110 function 0 of a
 111 .Tn PCI
 112 device, it is a
 113 .Em multi-function
 114 device, which contains several (similar or independent) functions on
 115 one chip.
 116 .Pp
 117 All invocations of
 118 .Nm
 119 except for
 120 .Fl l
 121 require a
 122 .Ar selector
 123 of the form
 124 .Li pci Ns Va bus Ns \&: Ns Va device
 125 (optionally followed by
 126 .Li \&: Ns Va function ) .
 127 A final colon may be appended and
 128 will be ignored; this is so that the first column in the output of
 129 .Nm
 130 .Fl l
 131 can be used without modification.
 132 All numbers are base 10.
 133 .Pp
 134 With the
 135 .Fl a
 136 flag,
 137 .Nm
 138 determines whether any driver has been assigned to the device
 139 identified by
 140 .Ar selector .
 141 An exit status of zero indicates that the device has a driver;
 142 non-zero indicates that it does not.
 143 .Pp
 144 The
 145 .Fl r
 146 option reads a configuration space register at byte offset
 147 .Ar addr
 148 of device
 149 .Ar selector
 150 and prints out its value in hexadecimal.
 151 The optional second address
 152 .Ar addr2
 153 specifies a range to read.
 154 The
 155 .Fl w
 156 option writes the
 157 .Ar value
 158 into a configuration space register at byte offset
 159 .Ar addr
 160 of device
 161 .Ar selector .
 162 For both operations, the flags
 163 .Fl b
 164 and
 165 .Fl h
 166 select the width of the operation;
 167 .Fl b
 168 indicates a byte operation, and
 169 .Fl h
 170 indicates a halfword (two-byte) operation.
 171 The default is to read or
 172 write a longword (four bytes).
 173 .Sh ENVIRONMENT
 174 The PCI vendor/device information database is normally read from
 175 .Pa /usr/share/misc/pci_vendors .
 176 This path can be overridden by setting the environment variable
 177 .Ev PCICONF_VENDOR_DATABASE .
 178 .Sh SEE ALSO
 179 .Xr ioctl 2 ,
 180 .Xr pci 4 ,
 181 .Xr kldload 8
 182 .Sh HISTORY
 183 The
 184 .Nm
 185 utility appeared first in
 186 .Fx 2.2 .
 187 The
 188 .Fl a
 189 option was added for
 190 .Tn PCI
 191 KLD support in
 192 .Fx 3.0 .
 193 .Sh AUTHORS
 194 .An -nosplit
 195 The
 196 .Nm
 197 utility was written by
 198 .An Stefan Esser
 199 and
 200 .An Garrett Wollman .
 201 .Sh BUGS
 202 The
 203 .Fl b
 204 and
 205 .Fl h
 206 options are implemented in
 207 .Nm ,
 208 but not in the underlying
 209 .Xr ioctl 2 .
 210 .Pp
 211 It might be useful to give non-root users access to the
 212 .Fl a
 213 and
 214 .Fl r
 215 options.
 216 But only root will be able to execute a
 217 .Nm kldload
 218 to provide the device with a driver KLD, and reading of configuration space
 219 registers may cause a failure in badly designed
 220 .Tn PCI
 221 chips.