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.