diff mbox series

[v4,14/23] docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage...

Message ID 20201124080159.11912-15-paul@xen.org (mailing list archive)
State Superseded
Headers show
Series xl / libxl: named PCI pass-through devices | expand

Commit Message

Paul Durrant Nov. 24, 2020, 8:01 a.m. UTC 
From: Paul Durrant <pdurrant@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 <pdurrant@amazon.com>
---
Cc: Ian Jackson <iwj@xenproject.org>
Cc: Wei Liu <wl@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

Comments

Oleksandr Andrushchenko Dec. 1, 2020, 3:25 p.m. UTC | #1 
Hi, Paul!

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

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

Thank you,

Oleksandr

> ---
> Cc: Ian Jackson <iwj@xenproject.org>
> Cc: Wei Liu <wl@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>
>
diff mbox series

Patch

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>