[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


  • To: Paul Durrant <paul@xxxxxxx>, "xen-devel@xxxxxxxxxxxxxxxxxxxx" <xen-devel@xxxxxxxxxxxxxxxxxxxx>
  • From: Oleksandr Andrushchenko <Oleksandr_Andrushchenko@xxxxxxxx>
  • Date: Tue, 1 Dec 2020 15:25:10 +0000
  • Accept-language: en-US
  • Arc-authentication-results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=epam.com; dmarc=pass action=none header.from=epam.com; dkim=pass header.d=epam.com; arc=none
  • Arc-message-signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=GgiuTfaLIZL8CHXQHuicwvFuL4rzvcjz2zfwZYquH4Y=; b=XPHrc3tkYhRQduR8vFuTlNOc5iBPjQdPGaP1cXlHhyxWz4jH4zHQFJQK7NnIh8PRK78XA6HD6R4HPjAfzHezlTWPRBFlyG29RJjjbIbSr0ndUGiPlwXPvELQ551Owwmx5L0ZOh5xHf73je0oFmlb8BgWyUy763RbSKSNIe+pOwm9vq25VVM6oYusYf2c0J8ZbbhHMYWAICHaVzx8KdhczarZzv/aM3MwK22CPFa6ychsaboN7gVOsNlW4tsfZ/PlTa1KFvjx0c0+7mb/eGtZPpKQj6PyiVK2JC/f7LQtaD7gkUyVkWv22bznGADhJ+uO494yKstMEk8zkpQfYSv5QQ==
  • Arc-seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=eck9nOODJqaG1hRz8LUzU/DYRkA2ppcegsy9r8+zgQlitrtlLc44mT9CclVjzF4nWzKKkZXzk/Bpp4s8fXUUOboVhNlGBztn6P+7at1r2/LFBQiaHl++COOtlHpsFzdbWWk7mA54O8RGpm0FLuycFOvc7qSyJdkf+rkgwP+osG12qB2GqOl+2BwzZVKU08xBiE9YdTMGgFM5qeQZPB+KsivFwlvKWZUPl5TEfWgm4SwlxpO09YAawOdLkvzkRrGJVWZW84kyy5mJkHt+L2K1h/5n/MmFlN94waaYke+mLYeK8H3NunNOXnq3MNPC0VG48Qyjx51kJOmU8Jh2MGwBcg==
  • Authentication-results: xen.org; dkim=none (message not signed) header.d=none;xen.org; dmarc=none action=none header.from=epam.com;
  • Cc: Paul Durrant <pdurrant@xxxxxxxxxx>, Ian Jackson <iwj@xxxxxxxxxxxxxx>, Wei Liu <wl@xxxxxxx>
  • Delivery-date: Tue, 01 Dec 2020 15:25:20 +0000
  • List-id: Xen developer discussion <xen-devel.lists.xenproject.org>
  • Thread-index: AQHWx/Yo8BmqKuHo0UWe0VurdxLGFw==
  • Thread-topic: [PATCH v4 14/23] docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage...

Hi, Paul!

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

Reviewed-by: Oleksandr Andrushchenko <oleksandr_andrushchenko@xxxxxxxx>

Thank you,

Oleksandr

> ---
> Cc: Ian Jackson <iwj@xxxxxxxxxxxxxx>
> Cc: Wei Liu <wl@xxxxxxx>
> ---
>   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>
>   

 


Rackspace

Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.