From nobody Tue Feb 10 05:17:00 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1606206672; cv=none; d=zohomail.com; s=zohoarc; b=mWmLWO3d5DNPqSvIMfE1UbBJoMbfEth2tYXyeC1LFeB5jm3KwrH+UF7GmNVBBQi/5Pu9rz/4MY1+JTH8jf0K7H14mu5jFLp/PrJD+zg28ygBwyG3fBf9oxUoN5h42ZQKWMZyT/Esib5w78ySoPSCnn6bQtEPtKFwNwOScSRSfqc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1606206672; h=Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:Message-ID:References:Sender:Subject:To; bh=z6HgaaJxE43aYUfbefthFXj4bV6TUshSIIqyN3QunIw=; b=Hs5HLSSv+IGj3dza2qneDLFRI1EDUwSGC69AucHbWtHQn9m6T+jb4G3MS+8CdohEwAX+CouM5VmLpWs0z4S+SOKGHaY/SCGqYlRQIvsNVg4fFhU7RPcPTFL4NIn5L7yNIdFxV8+wPV5XmqqVVrTXgf8AcrhnVWwVmRTRLS/ORgk= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of lists.xenproject.org designates 192.237.175.120 as permitted sender) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1606206672682560.2763089732973; Tue, 24 Nov 2020 00:31:12 -0800 (PST) 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 Received: by outflank-mailman (output) from mailman id 35506.67073; Tue, 24 Nov 2020 08:30: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 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 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 X-Outflank-Mailman: Message body and most headers restored to incoming version 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=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From; bh=z6HgaaJxE43aYUfbefthFXj4bV6TUshSIIqyN3QunIw=; b=KvNaN7Gc1rXGzOL5ZtUOdh6i4 UQAFI11D88dYwfC+M6zZBs5xlHyu8ud+YycOoKhQRRkYYUy7216pMZ2//YOb1YtY4woooA+5jTQTj SgZcLH8Oi3bSlvFuuoEC0Z0f7/+FyoX1xsf85MLecSQ+9/ClBlgjZkLGrQifKXJqcF8Ww=; 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> X-ZohoMail-DKIM: pass (identity @xen.org) Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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 documentati= on 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-configur= ation.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 =20 =3Dhead1 SYNTAX =20 -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. =20 -Each B has the form of -B<[DDDD:]BB:DD.F[@VSLOT],KEY=3DVALUE,KEY=3DVALUE,...> 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: + +=3Dover 4 + + [[@,][=3D,]* + [=3D,]* + +=3Dback + +For example, these strings are equivalent: =20 =3Dover 4 =20 -=3Ditem B<[DDDD:]BB:DD.F> + 36:00.0@20,seize=3D1 + 36:00.0,vslot=3D20,seize=3D1 + bdf=3D36:00.0,vslot=3D20,seize=3D1 =20 -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. +=3Dback + +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 "=3D" 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 t= han +B will be ignored. + +=3Dhead1 Positional Parameters + +=3Dover 4 + +=3Ditem B=3DI + +=3Dover 4 =20 -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. +=3Ditem Description =20 -=3Ditem B<@VSLOT> +This identifies the PCI device from the host perspective. =20 -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. =20 -=3Ditem B +=3Ditem Default Value + +None. This parameter is mandatory as it identifies the device. + +=3Dback + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem 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 dom= ain +and bus numbers are always 0. + +B This parameter is always parsed as a hexidecimal value. + +=3Ditem Default Value + +None. This parameter is not mandatory. An available B will be selec= ted +if this parameter is not specified. + +=3Dback + +=3Dback + +=3Dhead1 Other Parameters and Flags + +=3Dover 4 + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem Description =20 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. =20 -=3Ditem B +=3Ditem Default Value + +0 + +=3Dback + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem Description =20 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. + +=3Ditem 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). =20 -=3Ditem B +=3Dback + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem Description =20 -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. =20 -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. =20 -=3Ditem B +=3Ditem Default Value + +0 + +=3Dback + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem Description =20 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. + +=3Ditem Default Value + +0 =20 -=3Ditem B +=3Dback + +=3Ditem B=3DI + +=3Dover 4 + +=3Ditem Description =20 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. =20 -Note: this would override global B option. +B: This overrides the global B option. + +=3Ditem Default Value + +"strict" + +=3Dback =20 =3Dback --=20 2.11.0