Hi, Paul!

On 11/24/20 10:01 AM, Paul Durrant wrote:
> From: Paul Durrant <pdurr...@amazon.com>
>
> ... 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 <pdurr...@amazon.com>

Reviewed-by: Oleksandr Andrushchenko <oleksandr_andrushche...@epam.com>

Thank you,

Oleksandr

> ---
> Cc: Ian Jackson <i...@xenproject.org>
> Cc: Wei Liu <w...@xen.org>
> ---
>   docs/man/xl-pci-configuration.5.pod | 78 
> +++++++++++++++++++++++++++++++++++++
>   docs/man/xl.cfg.5.pod.in            | 68 +-------------------------------
>   2 files changed, 79 insertions(+), 67 deletions(-)
>   create mode 100644 docs/man/xl-pci-configuration.5.pod
>
> 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<PCI_SPEC_STRING> which is used by
> +the L<xl.cfg(5)> pci configuration option, and related L<xl(1)> commands.
> +
> +Each B<PCI_SPEC_STRING> 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<DDDD>), Bus (B<BB>), Device (B<DD>) and Function (B<F>) syntax. This is
> +the same scheme as used in the output of B<lspci(1)> for the device in
> +question.
> +
> +Note: by default B<lspci(1)> will omit the domain (B<DDDD>) if it
> +is zero and it is optional here also. You may specify the function
> +(B<F>) 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<DD> which the guest sees. In a
> +guest B<DDDD> and B<BB> are C<0000:00>.
> +
> +=item B<permissive=BOOLEAN>
> +
> +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<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.
> +
> +=item B<msitranslate=BOOLEAN>
> +
> +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<seize=BOOLEAN>
> +
> +Tells B<xl> to automatically attempt to re-assign a device to
> +pciback if it is not already assigned.
> +
> +B<WARNING:> If you set this option, B<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.
> +
> +=item B<power_mgmt=BOOLEAN>
> +
> +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<rdm_policy=STRING>
> +
> +B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm>
> +option but just specific to a given device. The default is "relaxed".
> +
> +Note: this would override global B<rdm> option.
> +
> +=back
> diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in
> index 0532739c1f..b00644e852 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<controller> option is 
> specified.
>   =item B<pci=[ "PCI_SPEC_STRING", "PCI_SPEC_STRING", ...]>
>   
>   Specifies the host PCI devices to passthrough to this guest.
> -Each B<PCI_SPEC_STRING> 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<DDDD>), Bus (B<BB>), Device (B<DD>) and Function (B<F>) syntax. This is
> -the same scheme as used in the output of B<lspci(1)> for the device in
> -question.
> -
> -Note: by default B<lspci(1)> will omit the domain (B<DDDD>) if it
> -is zero and it is optional here also. You may specify the function
> -(B<F>) 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<DD> which the guest sees. In a
> -guest B<DDDD> and B<BB> are C<0000:00>.
> -
> -=item B<permissive=BOOLEAN>
> -
> -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<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.
> -
> -=item B<msitranslate=BOOLEAN>
> -
> -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<seize=BOOLEAN>
> -
> -Tells B<xl> to automatically attempt to re-assign a device to
> -pciback if it is not already assigned.
> -
> -B<WARNING:> If you set this option, B<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.
> -
> -=item B<power_mgmt=BOOLEAN>
> -
> -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<rdm_policy=STRING>
> -
> -B<(HVM/x86 only)> This is the same as the policy setting inside the B<rdm>
> -option but just specific to a given device. The default is "relaxed".
> -
> -Note: this would override global B<rdm> option.
> -
> -=back
> +See L<xl-pci-configuration(5)> for more details.
>   
>   =item B<pci_permissive=BOOLEAN>
>   

Reply via email to