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