1xl-pci-configuration(5) Xen xl-pci-configuration(5)
2
6 xl-pci-configuration - XL PCI Configuration Syntax
7
9 This document specifies the format for BDF and PCI_SPEC_STRING which
10 are used by the xl.cfg(5) pci configuration option, and related xl(1)
11 commands.
12 A BDF has the following form:
14 [DDDD:]BB:SS.F
16 DDDD is the domain number, BB is the bus number, SS is the device (or
18 slot) number, and F is the function number. This is the same scheme as
19 used in the output of lspci(1) for the device in question. By default
20 lspci(1) will omit the domain (DDDD) if it is zero and hence a zero
21 value for domain may also be omitted when specifying a BDF.
22 Each PCI_SPEC_STRING has the one of the forms:
24 [<bdf>[@<vslot>,][<key>=<value>,]*
26 [<key>=<value>,]*
27 For example, these strings are equivalent:
29 36:00.0@20,seize=1
31 36:00.0,vslot=20,seize=1
32 bdf=36:00.0,vslot=20,seize=1
33 More formally, the string is a series of comma-separated keyword/value
35 pairs, flags and positional parameters. Parameters which are not bare
36 keywords and which do not contain "=" symbols are assigned to the
37 positional parameters, in the order specified below. The positional
38 parameters may also be specified by name.
39 Each parameter may be specified at most once, either as a positional
41 parameter or a named parameter. Default values apply if the parameter
42 is not specified, or if it is specified with an empty value (whether
43 positionally or explicitly).
44 NOTE: In context of xl pci-detach (see xl(1)), parameters other than
46 bdf or name will be ignored.
47
49 bdf=BDF
50 Description
51 This identifies the PCI device from the host perspective.
52 In the context of a PCI_SPEC_STRING you may specify the
54 function (F) as * to indicate all functions of a multi-function
55 device.
56 Default Value
58 None. This parameter is mandatory in its positional form. As a
59 non-positional parameter it is also mandatory unless a name
60 parameter is present, in which case bdf must not be present
61 since the name will be used to find the bdf in the list of
62 assignable devices. See xl(1) for more information on naming
63 assignable devices.
64 vslot=NUMBER
66 Description
67 Specifies the virtual slot (device) number where the guest will
68 see this device. For example, running lspci(1) in a Linux guest
69 where vslot was specified as 8 would identify the device as
70 "00:08.0". Virtual domain and bus numbers are always 0.
71 NOTE: This parameter is always parsed as a hexidecimal value.
73 Default Value
75 None. This parameter is not mandatory. An available vslot will
76 be selected if this parameter is not specified.
77
79 permissive=BOOLEAN
80 Description
81 By default pciback only allows PV guests to write "known safe"
82 values into PCI configuration space, likewise QEMU (both qemu-
83 xen and qemu-xen-traditional) imposes the same constraint on
84 HVM guests. However, many devices require writes to other
85 areas of the configuration space in order to operate properly.
86 This option tells the backend (pciback or QEMU) to allow all
87 writes to the PCI configuration space of this device by this
88 domain.
89 This option should be enabled with caution: it gives the guest
91 much more control over the device, which may have security or
92 stability implications. It is recommended to only enable this
93 option for trusted VMs under administrator's control.
94 Default Value
96 0
97 msitranslate=BOOLEAN
99 Description
100 Specifies that MSI-INTx translation should be turned on for the
101 PCI device. When enabled, MSI-INTx translation will always
102 enable MSI on the PCI device regardless of whether the guest
103 uses INTx or MSI.
104 Default Value
106 Some device drivers, such as NVIDIA's, detect an inconsistency
107 and do not function when this option is enabled. Therefore the
108 default is false (0).
109 seize=BOOLEAN
111 Description
112 Tells xl(1) to automatically attempt to make the device
113 assignable to guests if that has not already been done by the
114 pci-assignable-add command.
115 WARNING: If you set this option, xl will gladly re-assign a
117 critical system device, such as a network or a disk controller
118 being used by dom0 without confirmation. Please use with care.
119 Default Value
121 0
122 power_mgmt=BOOLEAN
124 Description
125 (HVM only) Specifies that the VM should be able to program the
126 D0-D3hot power management states for the PCI device.
127 Default Value
129 0
130 rdm_policy=STRING
132 Description
133 (HVM/x86 only) This is the same as the policy setting inside
134 the rdm option in xl.cfg(5) but just specific to a given
135 device.
136 NOTE: This overrides the global rdm option.
138 Default Value
140 "strict"
141 name=STRING
143 Description
144 This is the name given when the BDF was made assignable. See
145 xl(1) for more information on naming assignable devices.
146 Default Value
148 None. This parameter must not be present if a bdf parameter is
149 present. If a bdf parameter is not present then name is
150 mandatory as it is required to look up the BDF in the list of
151 assignable devices.
1524.17.2 2023-11-14 xl-pci-configuration(5)