.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "xl-pci-configuration 5"
.TH xl-pci-configuration 5 2024-03-09 4.17.4-pre Xen
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
xl\-pci\-configuration \- XL PCI Configuration Syntax
.SH SYNTAX
.IX Header "SYNTAX"
This document specifies the format for \fBBDF\fR and \fBPCI_SPEC_STRING\fR which are
used by the \fBxl.cfg\fR\|(5) pci configuration option, and related \fBxl\fR\|(1)
commands.
.PP
A \fBBDF\fR has the following form:
.PP
.Vb 1
\&    [DDDD:]BB:SS.F
.Ve
.PP
\&\fBDDDD\fR is the domain number, \fBBB\fR is the bus number, \fBSS\fR is the device (or
slot) number, and \fBF\fR is the function number. This is the same scheme as
used in the output of \fBlspci\fR\|(1) for the device in question. By default
\&\fBlspci\fR\|(1) will omit the domain (\fBDDDD\fR) if it is zero and hence a zero
value for domain may also be omitted when specifying a \fBBDF\fR.
.PP
Each \fBPCI_SPEC_STRING\fR has the one of the forms:
.Sp
.Vb 2
\&    [<bdf>[@<vslot>,][<key>=<value>,]*
\&    [<key>=<value>,]*
.Ve
.PP
For example, these strings are equivalent:
.Sp
.Vb 3
\&    36:00.0@20,seize=1
\&    36:00.0,vslot=20,seize=1
\&    bdf=36:00.0,vslot=20,seize=1
.Ve
.PP
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.
.PP
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).
.PP
\&\fBNOTE\fR: In context of \fBxl pci-detach\fR (see \fBxl\fR\|(1)), parameters other than
\&\fBbdf\fR or \fBname\fR will be ignored.
.SH "Positional Parameters"
.IX Header "Positional Parameters"
.IP \fBbdf\fR=\fIBDF\fR 4
.IX Item "bdf=BDF"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
This identifies the PCI device from the host perspective.
.Sp
In the context of a \fBPCI_SPEC_STRING\fR you may specify the function (\fBF\fR) as
\&\fB*\fR to indicate all functions of a multi-function device.
.IP "Default Value" 4
.IX Item "Default Value"
None. This parameter is mandatory in its positional form. As a non-positional
parameter it is also mandatory unless a \fBname\fR parameter is present, in
which case \fBbdf\fR must not be present since the \fBname\fR will be used to find
the \fBbdf\fR in the list of assignable devices. See \fBxl\fR\|(1) for more information
on naming assignable devices.
.RE
.RS 4
.RE
.IP \fBvslot\fR=\fINUMBER\fR 4
.IX Item "vslot=NUMBER"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
Specifies the virtual slot (device) number where the guest will see this
device. For example, running \fBlspci\fR\|(1) in a Linux guest where \fBvslot\fR
was specified as \f(CW8\fR would identify the device as \f(CW\*(C`00:08.0\*(C'\fR. Virtual domain
and bus numbers are always 0.
.Sp
\&\fBNOTE:\fR This parameter is always parsed as a hexidecimal value.
.IP "Default Value" 4
.IX Item "Default Value"
None. This parameter is not mandatory. An available \fBvslot\fR will be selected
if this parameter is not specified.
.RE
.RS 4
.RE
.SH "Other Parameters and Flags"
.IX Header "Other Parameters and Flags"
.IP \fBpermissive\fR=\fIBOOLEAN\fR 4
.IX Item "permissive=BOOLEAN"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
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.
.Sp
\&\fBThis option should be enabled with caution:\fR 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.
.IP "Default Value" 4
.IX Item "Default Value"
0
.RE
.RS 4
.RE
.IP \fBmsitranslate\fR=\fIBOOLEAN\fR 4
.IX Item "msitranslate=BOOLEAN"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
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.
.IP "Default Value" 4
.IX Item "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).
.RE
.RS 4
.RE
.IP \fBseize\fR=\fIBOOLEAN\fR 4
.IX Item "seize=BOOLEAN"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
Tells \fBxl\fR\|(1) to automatically attempt to make the device assignable to
guests if that has not already been done by the \fBpci-assignable-add\fR
command.
.Sp
\&\fBWARNING:\fR 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.
.IP "Default Value" 4
.IX Item "Default Value"
0
.RE
.RS 4
.RE
.IP \fBpower_mgmt\fR=\fIBOOLEAN\fR 4
.IX Item "power_mgmt=BOOLEAN"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
\&\fB(HVM only)\fR Specifies that the VM should be able to program the
D0\-D3hot power management states for the PCI device.
.IP "Default Value" 4
.IX Item "Default Value"
0
.RE
.RS 4
.RE
.IP \fBrdm_policy\fR=\fISTRING\fR 4
.IX Item "rdm_policy=STRING"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
\&\fB(HVM/x86 only)\fR This is the same as the policy setting inside the \fBrdm\fR
option in \fBxl.cfg\fR\|(5) but just specific to a given device.
.Sp
\&\fBNOTE\fR: This overrides the global \fBrdm\fR option.
.IP "Default Value" 4
.IX Item "Default Value"
"strict"
.RE
.RS 4
.RE
.IP \fBname\fR=\fISTRING\fR 4
.IX Item "name=STRING"
.RS 4
.PD 0
.IP Description 4
.IX Item "Description"
.PD
This is the name given when the \fBBDF\fR was made assignable. See \fBxl\fR\|(1) for
more information on naming assignable devices.
.IP "Default Value" 4
.IX Item "Default Value"
None. This parameter must not be present if a \fBbdf\fR parameter is present.
If a \fBbdf\fR parameter is not present then \fBname\fR is mandatory as it is
required to look up the \fBBDF\fR in the list of assignable devices.
.RE
.RS 4
.RE