From mboxrd@z Thu Jan 1 00:00:00 1970 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.8 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 8E2FAC56201 for ; Tue, 24 Nov 2020 08:31:02 +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 F316520708 for ; Tue, 24 Nov 2020 08:31:01 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=pass (1024-bit key) header.d=xen.org header.i=@xen.org header.b="KvNaN7Gc" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org F316520708 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.35506.67073 (Exim 4.92) (envelope-from ) id 1khTio-0003R2-Er; Tue, 24 Nov 2020 08:30:46 +0000 X-Outflank-Mailman: Message body and most headers restored to incoming version Received: by outflank-mailman (output) from mailman id 35506.67073; Tue, 24 Nov 2020 08:30:46 +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 1khTio-0003Qq-AV; Tue, 24 Nov 2020 08:30:46 +0000 Received: by outflank-mailman (input) for mailman id 35506; Tue, 24 Nov 2020 08:30:45 +0000 Received: from mail.xenproject.org ([104.130.215.37]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1khTim-0003PL-UL for xen-devel@lists.xenproject.org; Tue, 24 Nov 2020 08:30:44 +0000 Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1khTim-0006ah-3v; Tue, 24 Nov 2020 08:30:44 +0000 Received: from ec2-54-145-241-208.compute-1.amazonaws.com ([54.145.241.208] helo=ip-10-0-29-170.ec2.internal) by xenbits.xenproject.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1khTH3-0001hp-Rm; Tue, 24 Nov 2020 08:02:05 +0000 Received: from mail.xenproject.org ([104.130.215.37]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1khTim-0003PL-UL for xen-devel@lists.xenproject.org; Tue, 24 Nov 2020 08:30:44 +0000 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=KvNaN7Gc1rXGzOL5ZtUOdh6i4 UQAFI11D88dYwfC+M6zZBs5xlHyu8ud+YycOoKhQRRkYYUy7216pMZ2//YOb1YtY4woooA+5jTQTj SgZcLH8Oi3bSlvFuuoEC0Z0f7/+FyoX1xsf85MLecSQ+9/ClBlgjZkLGrQifKXJqcF8Ww=; Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1khTim-0006ah-3v; Tue, 24 Nov 2020 08:30:44 +0000 Received: from ec2-54-145-241-208.compute-1.amazonaws.com ([54.145.241.208] helo=ip-10-0-29-170.ec2.internal) by xenbits.xenproject.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1khTH3-0001hp-Rm; Tue, 24 Nov 2020 08:02:05 +0000 From: Paul Durrant To: xen-devel@lists.xenproject.org Cc: Paul Durrant , Ian Jackson , Wei Liu Subject: [PATCH v4 15/23] docs/man: improve documentation of PCI_SPEC_STRING... Date: Tue, 24 Nov 2020 08:01:51 +0000 Message-Id: <20201124080159.11912-16-paul@xen.org> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20201124080159.11912-1-paul@xen.org> References: <20201124080159.11912-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 -- 2.11.0