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