From patchwork Tue Dec 8 19:30:24 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Paul Durrant X-Patchwork-Id: 11959435 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.7 required=3.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER, INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id A3DD9C4361B for ; Tue, 8 Dec 2020 20:01:03 +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 69FD523C40 for ; Tue, 8 Dec 2020 20:01:03 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 69FD523C40 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.47760.84512 (Exim 4.92) (envelope-from ) id 1kmjAE-0004qE-IA; Tue, 08 Dec 2020 20:00:46 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 47760.84512; Tue, 08 Dec 2020 20:00:46 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAE-0004q2-EX; Tue, 08 Dec 2020 20:00:46 +0000 Received: by outflank-mailman (input) for mailman id 47760; Tue, 08 Dec 2020 20:00:45 +0000 Received: from mail.xenproject.org ([104.130.215.37]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAD-0004oq-Iz for xen-devel@lists.xenproject.org; Tue, 08 Dec 2020 20:00:45 +0000 Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAC-00086G-Nq; Tue, 08 Dec 2020 20:00:44 +0000 Received: from host86-183-162-145.range86-183.btcentralplus.com ([86.183.162.145] helo=desktop.home) by xenbits.xenproject.org with esmtpsa (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1kmihL-0001p0-BW; Tue, 08 Dec 2020 19:30:55 +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" DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=xen.org; s=20200302mail; h=Content-Transfer-Encoding:MIME-Version:References: In-Reply-To:Message-Id:Date:Subject:Cc:To:From; bh=Kp5JHM/PcDPgoyQFpS4CPrVmdU0OAzBzGq/q/o/48HU=; b=RwuXlpVlGqqwSfs9ckruZrDqFD c7NWlIYHncocBbwbUaf7sSbkXzqOZiFW5VsVz3PrS6OiqyckaYsi/KW5Z+v9bPqm05nHRVE2uKQnx pP1OR8hKo4CSiBDHjvE3K7nbIX/GFrLm7g9w3jENbMvRX5PEU4EwBTmN47EOXHcKCxCY=; From: Paul Durrant To: xen-devel@lists.xenproject.org Cc: Paul Durrant , Wei Liu , Ian Jackson Subject: [PATCH v6 16/25] docs/man: improve documentation of PCI_SPEC_STRING... Date: Tue, 8 Dec 2020 19:30:24 +0000 Message-Id: <20201208193033.11306-17-paul@xen.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20201208193033.11306-1-paul@xen.org> References: <20201208193033.11306-1-paul@xen.org> MIME-Version: 1.0 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 Acked-by: Wei Liu --- Cc: Ian Jackson --- 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 72a27bd95dec..4dd73bc498d6 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