1=encoding utf8
2
3=head1 NAME
4
5xl-pci-configuration - XL PCI Configuration Syntax
6
7=head1 SYNTAX
8
9This document specifies the format for B<BDF> and B<PCI_SPEC_STRING> which are
10used by the L<xl.cfg(5)> pci configuration option, and related L<xl(1)>
11commands.
12
13A B<BDF> has the following form:
14
15    [DDDD:]BB:SS.F
16
17B<DDDD> is the domain number, B<BB> is the bus number, B<SS> is the device (or
18slot) number, and B<F> is the function number. This is the same scheme as
19used in the output of L<lspci(1)> for the device in question. By default
20L<lspci(1)> will omit the domain (B<DDDD>) if it is zero and hence a zero
21value for domain may also be omitted when specifying a B<BDF>.
22
23Each B<PCI_SPEC_STRING> has the one of the forms:
24
25=over 4
26
27    [<bdf>[@<vslot>,][<key>=<value>,]*
28    [<key>=<value>,]*
29
30=back
31
32For example, these strings are equivalent:
33
34=over 4
35
36    36:00.0@20,seize=1
37    36:00.0,vslot=20,seize=1
38    bdf=36:00.0,vslot=20,seize=1
39
40=back
41
42More formally, the string is a series of comma-separated keyword/value
43pairs, flags and positional parameters.  Parameters which are not bare
44keywords and which do not contain "=" symbols are assigned to the
45positional parameters, in the order specified below.  The positional
46parameters may also be specified by name.
47
48Each parameter may be specified at most once, either as a positional
49parameter or a named parameter.  Default values apply if the parameter
50is not specified, or if it is specified with an empty value (whether
51positionally or explicitly).
52
53B<NOTE>: In context of B<xl pci-detach> (see L<xl(1)>), parameters other than
54B<bdf> or B<name> will be ignored.
55
56=head1 Positional Parameters
57
58=over 4
59
60=item B<bdf>=I<BDF>
61
62=over 4
63
64=item Description
65
66This identifies the PCI device from the host perspective.
67
68In the context of a B<PCI_SPEC_STRING> you may specify the function (B<F>) as
69B<*> to indicate all functions of a multi-function device.
70
71=item Default Value
72
73None. This parameter is mandatory in its positional form. As a non-positional
74parameter it is also mandatory unless a B<name> parameter is present, in
75which case B<bdf> must not be present since the B<name> will be used to find
76the B<bdf> in the list of assignable devices. See L<xl(1)> for more information
77on naming assignable devices.
78
79=back
80
81=item B<vslot>=I<NUMBER>
82
83=over 4
84
85=item Description
86
87Specifies the virtual slot (device) number where the guest will see this
88device. For example, running L<lspci(1)> in a Linux guest where B<vslot>
89was specified as C<8> would identify the device as C<00:08.0>. Virtual domain
90and bus numbers are always 0.
91
92B<NOTE:> This parameter is always parsed as a hexidecimal value.
93
94=item Default Value
95
96None. This parameter is not mandatory. An available B<vslot> will be selected
97if this parameter is not specified.
98
99=back
100
101=back
102
103=head1 Other Parameters and Flags
104
105=over 4
106
107=item B<permissive>=I<BOOLEAN>
108
109=over 4
110
111=item Description
112
113By default pciback only allows PV guests to write "known safe" values
114into PCI configuration space, likewise QEMU (both qemu-xen and
115qemu-xen-traditional) imposes the same constraint on HVM guests.
116However, many devices require writes to other areas of the configuration space
117in order to operate properly.  This option tells the backend (pciback or QEMU)
118to allow all writes to the PCI configuration space of this device by this
119domain.
120
121B<This option should be enabled with caution:> it gives the guest much
122more control over the device, which may have security or stability
123implications.  It is recommended to only enable this option for
124trusted VMs under administrator's control.
125
126=item Default Value
127
1280
129
130=back
131
132=item B<msitranslate>=I<BOOLEAN>
133
134=over 4
135
136=item Description
137
138Specifies that MSI-INTx translation should be turned on for the PCI
139device. When enabled, MSI-INTx translation will always enable MSI on
140the PCI device regardless of whether the guest uses INTx or MSI.
141
142=item Default Value
143
144Some device drivers, such as NVIDIA's, detect an inconsistency and do not
145function when this option is enabled. Therefore the default is false (0).
146
147=back
148
149=item B<seize>=I<BOOLEAN>
150
151=over 4
152
153=item Description
154
155Tells L<xl(1)> to automatically attempt to make the device assignable to
156guests if that has not already been done by the B<pci-assignable-add>
157command.
158
159B<WARNING:> If you set this option, L<xl> will gladly re-assign a critical
160system device, such as a network or a disk controller being used by
161dom0 without confirmation.  Please use with care.
162
163=item Default Value
164
1650
166
167=back
168
169=item B<power_mgmt>=I<BOOLEAN>
170
171=over 4
172
173=item Description
174
175B<(HVM only)> Specifies that the VM should be able to program the
176D0-D3hot power management states for the PCI device.
177
178=item Default Value
179
1800
181
182=back
183
184=item B<rdm_policy>=I<STRING>
185
186=over 4
187
188=item Description
189
190B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm>
191option in L<xl.cfg(5)> but just specific to a given device.
192
193B<NOTE>: This overrides the global B<rdm> option.
194
195=item Default Value
196
197"strict"
198
199=back
200
201=item B<name>=I<STRING>
202
203=over 4
204
205=item Description
206
207This is the name given when the B<BDF> was made assignable. See L<xl(1)> for
208more information on naming assignable devices.
209
210=item Default Value
211
212None. This parameter must not be present if a B<bdf> parameter is present.
213If a B<bdf> parameter is not present then B<name> is mandatory as it is
214required to look up the B<BDF> in the list of assignable devices.
215
216=back
217
218=back
219