From 1655a3085aa9097ac345bcbd3d4065b2fff2fa0a Mon Sep 17 00:00:00 2001 From: Paul Durrant Date: Tue, 13 Oct 2020 07:43:35 +0000 Subject: [PATCH] docs/man: improve documentation of PCI_SPEC_STRING... ... and prepare for adding support for non-positional parsing of 'bdf' and 'vslot' in a subsequent patch. Also document 'BDF' as a first-class parameter type and fix the documentation to state that the default value of 'rdm_policy' is actually 'strict', not 'relaxed', as can be seen in libxl__device_pci_setdefault(). Signed-off-by: Paul Durrant --- Cc: Ian Jackson Cc: Wei Liu --- docs/man/xl-pci-configuration.5.pod | 177 +++++++++++++++++++++++----- 1 file changed, 148 insertions(+), 29 deletions(-) diff --git a/docs/man/xl-pci-configuration.5.pod b/docs/man/xl-pci-configuration.5.pod index 72a27bd95d..4dd73bc498 100644 --- a/docs/man/xl-pci-configuration.5.pod +++ b/docs/man/xl-pci-configuration.5.pod @@ -6,32 +6,105 @@ 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. +This document specifies the format for B and B which are +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: +A B has the following form: + + [DDDD:]BB:SS.F + +B is the domain number, B is the bus number, B is the device (or +slot) number, and B is the function number. This is the same scheme as +used in the output of L for the device in question. By default +L will omit the domain (B) if it is zero and hence a zero +value for domain may also be omitted when specifying a B. + +Each B has the one of the forms: + +=over 4 + + [[@,][=,]* + [=,]* + +=back + +For example, these strings are equivalent: =over 4 -=item B<[DDDD:]BB:DD.F> + 36:00.0@20,seize=1 + 36:00.0,vslot=20,seize=1 + bdf=36:00.0,vslot=20,seize=1 -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. +=back + +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. + +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). + +B: In context of B (see L), parameters other than +B will be ignored. + +=head1 Positional Parameters + +=over 4 + +=item B=I + +=over 4 -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 Description -=item B<@VSLOT> +This identifies the PCI device from the host perspective. -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>. +In the context of a B you may specify the function (B) as +B<*> to indicate all functions of a multi-function device. -=item B +=item Default Value + +None. This parameter is mandatory as it identifies the device. + +=back + +=item B=I + +=over 4 + +=item Description + +Specifies the virtual slot (device) number where the guest will see this +device. For example, running L in a Linux guest where B +was specified as C<8> would identify the device as C<00:08.0>. Virtual domain +and bus numbers are always 0. + +B This parameter is always parsed as a hexidecimal value. + +=item Default Value + +None. This parameter is not mandatory. An available B will be selected +if this parameter is not specified. + +=back + +=back + +=head1 Other Parameters and Flags + +=over 4 + +=item B=I + +=over 4 + +=item Description By default pciback only allows PV guests to write "known safe" values into PCI configuration space, likewise QEMU (both qemu-xen and @@ -46,33 +119,79 @@ 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 +=item Default Value + +0 + +=back + +=item B=I + +=over 4 + +=item Description 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 +the PCI device regardless of whether the guest uses INTx or MSI. + +=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). -=item B +=back + +=item B=I + +=over 4 + +=item Description -Tells B to automatically attempt to re-assign a device to -pciback if it is not already assigned. +Tells L to automatically attempt to make the device assignable to +guests if that has not already been done by the B +command. -B If you set this option, B will gladly re-assign a critical +B If you set this option, L 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 +=item Default Value + +0 + +=back + +=item B=I + +=over 4 + +=item Description 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). +D0-D3hot power management states for the PCI device. + +=item Default Value + +0 -=item B +=back + +=item B=I + +=over 4 + +=item Description 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". +option in L but just specific to a given device. -Note: this would override global B option. +B: This overrides the global B option. + +=item Default Value + +"strict" + +=back =back -- 2.39.5