From patchwork Fri Oct 23 16:23:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Durrant X-Patchwork-Id: 11853949 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id C04A514B4 for ; Fri, 23 Oct 2020 16:27:13 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 85AF12192A for ; Fri, 23 Oct 2020 16:27:13 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=xen.org header.i=@xen.org header.b="Zz6BTj1c" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 85AF12192A Authentication-Results: mail.kernel.org; dmarc=none (p=none dis=none) header.from=xen.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from list by lists.xenproject.org with outflank-mailman.11204.29747 (Exim 4.92) (envelope-from ) id 1kVzti-00019L-3K; Fri, 23 Oct 2020 16:26:34 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 11204.29747; Fri, 23 Oct 2020 16:26:34 +0000 X-BeenThere: xen-devel@lists.xenproject.org List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Precedence: list Sender: "Xen-devel" Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kVzth-000197-RI; Fri, 23 Oct 2020 16:26:33 +0000 Received: by outflank-mailman (input) for mailman id 11204; Fri, 23 Oct 2020 16:26:32 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kVztg-0000v3-Hx for xen-devel@lists.xenproject.org; Fri, 23 Oct 2020 16:26:32 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id b97d7312-5e9d-4a2e-87ca-00498ffff7bc; Fri, 23 Oct 2020 16:26:22 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kVztV-0008O0-53; Fri, 23 Oct 2020 16:26:21 +0000 Received: from ec2-18-200-132-236.eu-west-1.compute.amazonaws.com ([18.200.132.236] helo=ip-10-0-185-232.eu-west-1.compute.internal) by xenbits.xenproject.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1kVzqo-000376-8v; Fri, 23 Oct 2020 16:23:34 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kVztg-0000v3-Hx for xen-devel@lists.xenproject.org; Fri, 23 Oct 2020 16:26:32 +0000 X-Inumbo-ID: b97d7312-5e9d-4a2e-87ca-00498ffff7bc Received: from mail.xenproject.org (unknown [104.130.215.37]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id b97d7312-5e9d-4a2e-87ca-00498ffff7bc; Fri, 23 Oct 2020 16:26:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=xen.org; s=20200302mail; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From; bh=z6HgaaJxE43aYUfbefthFXj4bV6TUshSIIqyN3QunIw=; b=Zz6BTj1cwZdakGQDRxN1PhsFE SHOWDggs1srSx+88vukhHOKibqNIrfxjy+A5ZtkyXQWRYZdhPJPBh3L0D7qDjEYwbXTY4AFZ+tXdu J9tevDgsgVKi2BzjsnW76OojdsJufMOcS0v3bZHOFDeia8RzNfHZc4gVV/U8iSSKewcEo=; Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kVztV-0008O0-53; Fri, 23 Oct 2020 16:26:21 +0000 Received: from ec2-18-200-132-236.eu-west-1.compute.amazonaws.com ([18.200.132.236] helo=ip-10-0-185-232.eu-west-1.compute.internal) by xenbits.xenproject.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1kVzqo-000376-8v; Fri, 23 Oct 2020 16:23:34 +0000 From: Paul Durrant To: xen-devel@lists.xenproject.org Cc: Paul Durrant , Ian Jackson , Wei Liu Subject: [PATCH 17/25] docs/man: improve documentation of PCI_SPEC_STRING... Date: Fri, 23 Oct 2020 16:23:06 +0000 Message-Id: <20201023162314.2235-18-paul@xen.org> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20201023162314.2235-1-paul@xen.org> References: <20201023162314.2235-1-paul@xen.org> From: Paul Durrant ... 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