setpci.man

   1 .TH setpci 8 "@TODAY@" "@VERSION@" "The PCI Utilities"
   2 .IX setpci
   3 .SH NAME
   4 setpci \- configure PCI devices
   5 .SH SYNOPSIS
   6 .B setpci
   7 .RB [ options ]
   8 .B devices
   9 .BR operations ...
  10
  11 .SH DESCRIPTION
  12 .PP
  13 .B setpci
  14 is a utility for querying and configuring PCI devices.
  15
  16 All numbers are entered in hexadecimal notation.
  17
  18 Root privileges are necessary for almost all operations, excluding reads
  19 of the standard header of the configuration space on some operating systems.
  20 Please see
  21 .BR lspci(8)
  22 for details on access rights.
  23
  24 .SH OPTIONS
  25
  26 .SS General options
  27 .TP
  28 .B -v
  29 Tells
  30 .I setpci
  31 to be verbose and display detailed information about configuration space accesses.
  32 .TP
  33 .B -f
  34 Tells
  35 .I setpci
  36 not to complain when there's nothing to do (when no devices are selected).
  37 This option is intended for use in widely-distributed configuration scripts
  38 where it's uncertain whether the device in question is present in the machine
  39 or not.
  40 .TP
  41 .B -D
  42 `Demo mode' -- don't write anything to the configuration registers.
  43 It's useful to try
  44 .B setpci -vD
  45 to verify that your complex sequence of
  46 .B setpci
  47 operations does what you think it should do.
  48 .TP
  49 .B --version
  50 Show
  51 .I setpci
  52 version. This option should be used stand-alone.
  53 .TP
  54 .B --help
  55 Show detailed help on available options. This option should be used stand-alone.
  56 .TP
  57 .B --dumpregs
  58 Show a list of all known PCI registers and capabilities. This option should be
  59 used stand-alone.
  60
  61 .SS PCI access options
  62 .PP
  63 The PCI utilities use the PCI library to talk to PCI devices (see
  64 \fBpcilib\fP(7) for details). You can use the following options to
  65 influence its behavior:
  66 .TP
  67 .B -A <method>
  68 The library supports a variety of methods to access the PCI hardware.
  69 By default, it uses the first access method available, but you can use
  70 this option to override this decision. See \fB-A help\fP for a list of
  71 available methods and their descriptions.
  72 .TP
  73 .B -O <param>=<value>
  74 The behavior of the library is controlled by several named parameters.
  75 This option allows to set the value of any of the parameters. Use \fB-O help\fP
  76 for a list of known parameters and their default values.
  77 .TP
  78 .B -H1
  79 Use direct hardware access via Intel configuration mechanism 1.
  80 (This is a shorthand for \fB-A intel-conf1\fP.)
  81 .TP
  82 .B -H2
  83 Use direct hardware access via Intel configuration mechanism 2.
  84 (This is a shorthand for \fB-A intel-conf2\fP.)
  85 .TP
  86 .B -G
  87 Increase debug level of the library.
  88
  89 .SH DEVICE SELECTION
  90 .PP
  91 Before each sequence of operations you need to select which devices you wish that
  92 operation to affect.
  93 .TP
  94 .B -s [[[[<domain>]:]<bus>]:][<slot>][.[<func>]]
  95 Consider only devices in the specified domain (in case your machine has several host bridges,
  96 they can either share a common bus number space or each of them can address a PCI domain
  97 of its own; domains are numbered from 0 to ffff), bus (0 to ff), slot (0 to 1f) and function (0 to 7).
  98 Each component of the device address can be omitted or set to "*", both meaning "any value". All numbers are
  99 hexadecimal.  E.g., "0:" means all devices on bus 0, "0" means all functions of device 0
 100 on any bus, "0.3" selects third function of device 0 on all buses and ".4" matches only
 101 the fourth function of each device.
 102 .TP
 103 .B -d [<vendor>]:[<device>]
 104 Select devices with specified vendor and device ID. Both ID's are given in
 105 hexadecimal and may be omitted or given as "*", both meaning "any value".
 106 .PP
 107 When
 108 .B -s
 109 and
 110 .B -d
 111 are combined, only devices that match both criteria are selected. When multiple
 112 options of the same kind are specified, the rightmost one overrides the others.
 113
 114 .SH OPERATIONS
 115 .PP
 116 There are two kinds of operations: reads and writes. To read a register, just specify
 117 its name. Writes have the form
 118 .IR name = value , value ...
 119 where each
 120 .I value
 121 is either a hexadecimal number or an expression of type
 122 .IR data : mask
 123 where both
 124 .I data
 125 and
 126 .I mask
 127 are hexadecimal numbers. In the latter case, only the bits corresponding to binary
 128 ones in the \fImask\fP are changed (technically, this is a read-modify-write operation).
 129
 130 .PP
 131 There are several ways how to identity a register:
 132 .IP \(bu
 133 Tell its address in hexadecimal.
 134 .IP \(bu
 135 Spell its name. Setpci knows the names of all registers in the standard configuration
 136 headers. Use `\fBsetpci --dumpregs\fP' to get the complete list.
 137 See PCI bus specifications for the precise meaning of these registers or consult
 138 \fBheader.h\fP or \fB/usr/include/pci/pci.h\fP for a brief sketch.
 139 .IP \(bu
 140 If the register is a part of a PCI capability, you can specify the name of the
 141 capability to get the address of its first register. See the names starting with
 142 `CAP_' or `ECAP_' in the \fB--dumpregs\fP output.
 143 .IP \(bu
 144 If the name of the capability is not known to \fBsetpci\fP, you can refer to it
 145 by its number in the form CAP\fBid\fP or ECAP\fBid\fP, where \fBid\fP is the numeric
 146 identifier of the capability in hexadecimal.
 147 .IP \(bu
 148 Each of the previous formats can be followed by \fB+offset\fP to add an offset
 149 (a hex number) to the address. This feature can be useful for addressing of registers
 150 living within a capability, or to modify parts of standard registers.
 151 .IP \(bu
 152 Finally, you should append a width specifier \fB.B\fP, \fB.W\fP, or \fB.L\fP to choose
 153 how many bytes (1, 2, or 4) should be transferred. The width can be omitted if you are
 154 referring to a register by its name and the width of the register is well known.
 155
 156 .PP
 157 All names of registers and width specifiers are case-insensitive.
 158
 159 .SH
 160 EXAMPLES
 161
 162 .IP COMMAND
 163 asks for the word-sized command register.
 164 .IP 4.w
 165 is a numeric address of the same register.
 166 .IP COMMAND.l
 167 asks for a 32-bit word starting at the location of the command register,
 168 i.e., the command and status registers together.
 169 .IP VENDOR_ID+1.b
 170 specifies the upper byte of the vendor ID register (remember, PCI is little-endian).
 171 .IP CAP_PM+2.w
 172 corresponds to the second word of the power management capability.
 173 .IP ECAP108.l
 174 asks for the first 32-bit word of the extended capability with ID 0x108.
 175
 176 .SH SEE ALSO
 177 .BR lspci (8),
 178 .BR pcilib (7)
 179
 180 .SH AUTHOR
 181 The PCI Utilities are maintained by Martin Mares <mj@ucw.cz>.