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.

