xl-pci-configuration(5)

📦
version 4.20.4+39-gf1e1321c87 · 21 versions
, in debian trixie

💅 xl-pci-configuration(5) — the XL PCI Configuration Syntax glow-up

Okay bestie, so this is a man page from the Xen fam, xl-pci-configuration(5) — and it's literally the whole handbook for how to write BDFs and PCI_SPEC_STRINGs. Those two cuties get used by the pci configuration option in xl.cfg(5), plus all the related xl(1) commands. So if you're doing PCI passthrough, this is your main character document. 🎀

✨ SYNTAX ✨

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

A BDF has this form:

[DDDD:]BB:SS.F

Let's break it down, because honestly it's giving coordinates:

  • DDDD — the domain number
  • BB — the bus number
  • SS — the device (or slot) number
  • F — the function number

It's the same scheme as the output of lspci(1) for the device in question. By default lspci(1) will omit the domain (DDDD) if it's zero — and that means a zero value for domain may also be omitted when you're specifying a BDF. So no stress, you can leave it out. 🦋

Each PCI_SPEC_STRING has one of these forms:

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

And for example, these strings are equivalent (yes, all three of them, no cap):

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

More formally — love a formal moment — 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. And the positional parameters may also be specified by name. Slay, flexibility. 💖

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's specified with an empty value (whether positionally or explicitly).

NOTE: In the context of xl pci-detach (see xl(1)), parameters other than bdf or name will be ignored. So don't come for them, they're not listening.

🌸 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. Mmm, wildcard energy. ⭐

Default Value — None. This parameter is mandatory in its positional form. As a non-positional parameter it's 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 info 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. Periodt.

NOTE: This parameter is always parsed as a hexadecimal value. 🙈

Default Value — None. This parameter is not mandatory. An available vslot will be selected if this parameter is not specified. She'll find a seat, don't worry. 💅

👑 Other Parameters and Flags 👑

permissive=BOOLEAN

Description — by default pciback only allows PV guests to write "known safe" values into PCI configuration space, and likewise QEMU (both qemu-xen and qemu-xen-traditional) imposes the same constraint on HVM guests. But like… 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's recommended to only enable this option for trusted VMs under administrator's control. Fr fr, be careful with this one. 😭

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). 💀 The more you know.

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. Like, she will not ask, she will just do it. 🫶 Use responsibly.

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. Device-specific erasure of the global setting, we love a local legend.

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's required to look up the BDF in the list of assignable devices. iykyk. 🌈

That's the whole vibe check completed, bestie. Go forth and configure your PCI devices with confidence. 🧚‍♀️

Cute little sign-off: this gorgeous page is from Xen version 4.20.5-pre, dated 2026-10-16. Stan. 💜
📦 where this page comes from