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.

4.17.4-pre                                         2024-04-01                            xl-pci-configuration(5)