NAME

xl-pci-configuration - XL PCI Configuration Syntax

SYNTAX

This document specifies the format for BDF and PCI_SPEC_STRING which are used by the xl.cfg(5) pci configuration option, and related xl(1) commands.

A BDF has the following form:

    [DDDD:]BB:SS.F

DDDD is the domain number, BB is the bus number, SS is the device (or slot) number, and F is the function number. This is the same scheme as used in the output of lspci(1) for the device in question. By default lspci(1) will omit the domain (DDDD) if it is zero and hence a zero value for domain may also be omitted when specifying a BDF.

Each PCI_SPEC_STRING has the one of the forms:

    [<bdf>[@<vslot>,][<key>=<value>,]*
    [<key>=<value>,]*

For example, these strings are equivalent:

    36:00.0@20,seize=1
    36:00.0,vslot=20,seize=1
    bdf=36:00.0,vslot=20,seize=1

More formally, the string is a series of comma-separated keyword/value pairs, flags and positional parameters. Parameters which are not bare keywords and which do not contain "=" symbols are assigned to the positional parameters, in the order specified below. The positional parameters may also be specified by name.

Each parameter may be specified at most once, either as a positional parameter or a named parameter. Default values apply if the parameter is not specified, or if it is specified with an empty value (whether positionally or explicitly).

NOTE: In context of xl pci-detach (see xl(1)), parameters other than bdf or name will be ignored.

Positional Parameters

bdf=BDF

Description: This identifies the PCI device from the host perspective.
In the context of a PCI_SPEC_STRING you may specify the function (F) as * to indicate all functions of a multi-function device.
Default Value: None. This parameter is mandatory in its positional form. As a non-positional parameter it is also mandatory unless a name parameter is present, in which case bdf must not be present since the name will be used to find the bdf in the list of assignable devices. See xl(1) for more information on naming assignable devices.

vslot=NUMBER

Description: Specifies the virtual slot (device) number where the guest will see this device. For example, running lspci(1) in a Linux guest where vslot was specified as 8 would identify the device as "00:08.0". Virtual domain and bus numbers are always 0.
NOTE: This parameter is always parsed as a hexidecimal value.
Default Value: None. This parameter is not mandatory. An available vslot will be selected if this parameter is not specified.

Other Parameters and Flags

permissive=BOOLEAN

Description: By default pciback only allows PV guests to write "known safe" values into PCI configuration space, likewise QEMU (both qemu-xen and qemu-xen-traditional) imposes the same constraint on HVM guests. However, many devices require writes to other areas of the configuration space in order to operate properly. This option tells the backend (pciback or QEMU) to allow all writes to the PCI configuration space of this device by this domain.
This option should be enabled with caution: it gives the guest much more control over the device, which may have security or stability implications. It is recommended to only enable this option for trusted VMs under administrator's control.
Default Value: 0

msitranslate=BOOLEAN

Description: Specifies that MSI-INTx translation should be turned on for the PCI device. When enabled, MSI-INTx translation will always enable MSI on the PCI device regardless of whether the guest uses INTx or MSI.
Default Value: Some device drivers, such as NVIDIA's, detect an inconsistency and do not function when this option is enabled. Therefore the default is false (0).

seize=BOOLEAN

Description: Tells xl(1) to automatically attempt to make the device assignable to guests if that has not already been done by the pci-assignable-add command.
WARNING: If you set this option, xl will gladly re-assign a critical system device, such as a network or a disk controller being used by dom0 without confirmation. Please use with care.
Default Value: 0

power_mgmt=BOOLEAN

Description: (HVM only) Specifies that the VM should be able to program the D0-D3hot power management states for the PCI device.
Default Value: 0

rdm_policy=STRING

Description: (HVM/x86 only) This is the same as the policy setting inside the rdm option in xl.cfg(5) but just specific to a given device.
NOTE: This overrides the global rdm option.
Default Value: "strict"

name=STRING

Description: This is the name given when the BDF was made assignable. See xl(1) for more information on naming assignable devices.
Default Value: None. This parameter must not be present if a bdf parameter is present. If a bdf parameter is not present then name is mandatory as it is required to look up the BDF in the list of assignable devices.