From: Paul Durrant Date: Tue, 8 Dec 2020 19:30:23 +0000 (+0000) Subject: docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage... X-Git-Tag: archive/raspbian/4.16.0+51-g0941d6cb-1+rpi1~2^2~42^2~1282 X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=581abb66a9ee5de403c97b2520960f65a878a0ff;p=xen.git docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage... ... and put it into a new xl-pci-configuration(5) manpage, akin to the xl-network-configration(5) and xl-disk-configuration(5) manpages. This patch moves the content of the section verbatim. A subsequent patch will improve the documentation, once it is in its new location. Signed-off-by: Paul Durrant Reviewed-by: Oleksandr Andrushchenko Acked-by: Wei Liu --- diff --git a/docs/man/xl-pci-configuration.5.pod b/docs/man/xl-pci-configuration.5.pod new file mode 100644 index 0000000000..72a27bd95d --- /dev/null +++ b/docs/man/xl-pci-configuration.5.pod @@ -0,0 +1,78 @@ +=encoding utf8 + +=head1 NAME + +xl-pci-configuration - XL PCI Configuration Syntax + +=head1 SYNTAX + +This document specifies the format for B which is used by +the L pci configuration option, and related L commands. + +Each B has the form of +B<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where: + +=over 4 + +=item B<[DDDD:]BB:DD.F> + +Identifies the PCI device from the host perspective in the domain +(B), Bus (B), Device (B
) and Function (B) syntax. This is +the same scheme as used in the output of B for the device in +question. + +Note: by default B will omit the domain (B) if it +is zero and it is optional here also. You may specify the function +(B) as B<*> to indicate all functions. + +=item B<@VSLOT> + +Specifies the virtual slot where the guest will see this +device. This is equivalent to the B
which the guest sees. In a +guest B and B are C<0000:00>. + +=item B + +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. + +B 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. + +=item B + +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. 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). + +=item B + +Tells B to automatically attempt to re-assign a device to +pciback if it is not already assigned. + +B If you set this option, B 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. + +=item B + +B<(HVM only)> Specifies that the VM should be able to program the +D0-D3hot power management states for the PCI device. The default is false (0). + +=item B + +B<(HVM/x86 only)> This is the same as the policy setting inside the B +option but just specific to a given device. The default is "relaxed". + +Note: this would override global B option. + +=back diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in index 12201a7e54..c8e017f950 100644 --- a/docs/man/xl.cfg.5.pod.in +++ b/docs/man/xl.cfg.5.pod.in @@ -1101,73 +1101,7 @@ option is valid only when the B option is specified. =item B Specifies the host PCI devices to passthrough to this guest. -Each B has the form of -B<[DDDD:]BB:DD.F[@VSLOT],KEY=VALUE,KEY=VALUE,...> where: - -=over 4 - -=item B<[DDDD:]BB:DD.F> - -Identifies the PCI device from the host perspective in the domain -(B), Bus (B), Device (B
) and Function (B) syntax. This is -the same scheme as used in the output of B for the device in -question. - -Note: by default B will omit the domain (B) if it -is zero and it is optional here also. You may specify the function -(B) as B<*> to indicate all functions. - -=item B<@VSLOT> - -Specifies the virtual slot where the guest will see this -device. This is equivalent to the B
which the guest sees. In a -guest B and B are C<0000:00>. - -=item B - -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. - -B 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. - -=item B - -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. 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). - -=item B - -Tells B to automatically attempt to re-assign a device to -pciback if it is not already assigned. - -B If you set this option, B 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. - -=item B - -B<(HVM only)> Specifies that the VM should be able to program the -D0-D3hot power management states for the PCI device. The default is false (0). - -=item B - -B<(HVM/x86 only)> This is the same as the policy setting inside the B -option but just specific to a given device. The default is "relaxed". - -Note: this would override global B option. - -=back +See L for more details. =item B