Annotation of embedaddon/pciutils/setpci.man, revision 1.1.1.1
1.1 misho 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>.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to setpci.man CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / pciutils