1xl-pci-configuration(5)               Xen              xl-pci-configuration(5)
2
3
4

NAME

6       xl-pci-configuration - XL PCI Configuration Syntax
7

SYNTAX

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
13       A BDF has the following form:
14
15           [DDDD:]BB:SS.F
16
17       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
23       Each PCI_SPEC_STRING has the one of the forms:
24
25           [<bdf>[@<vslot>,][<key>=<value>,]*
26           [<key>=<value>,]*
27
28       For example, these strings are equivalent:
29
30           36:00.0@20,seize=1
31           36:00.0,vslot=20,seize=1
32           bdf=36:00.0,vslot=20,seize=1
33
34       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
40       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
45       NOTE: In context of xl pci-detach (see xl(1)), parameters other than
46       bdf or name will be ignored.
47

Positional Parameters

49       bdf=BDF
50           Description
51               This identifies the PCI device from the host perspective.
52
53               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
57           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
65       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
72               NOTE: This parameter is always parsed as a hexidecimal value.
73
74           Default Value
75               None. This parameter is not mandatory. An available vslot will
76               be selected if this parameter is not specified.
77

Other Parameters and Flags

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
90               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
95           Default Value
96               0
97
98       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
105           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
110       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
116               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
120           Default Value
121               0
122
123       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
128           Default Value
129               0
130
131       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
137               NOTE: This overrides the global rdm option.
138
139           Default Value
140               "strict"
141
142       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
147           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.
152
153
154
1554.17.2                            2023-11-14           xl-pci-configuration(5)
Impressum