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