From nobody Tue Feb 10 06:25:40 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=1607457673; cv=none; d=zohomail.com; s=zohoarc; b=LrHMinYDnC2GTspFj/JglGPlzJWp3kGrVTy7fULpdmLsI4LknQG8wwO1XX0Q5jJBdhbg7gLqn24gPCsXd4eSAxxjCXRFjoCtOuA67wBFuo2fxTXL6uynOV9Unq2x9X7XJTyTzvIjMjIK3BDVEZJO9tnb734IpwFArn12mNDjKHM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1607457673; h=Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=UhlxfGmI/aEuEJYbZvO+wCWpWg3W+k9Y3YHBgam9bbQ=; b=eJ61tEzhamFSs7QC07pGcdR2XvB40dvRFLK+FpzNoY9qxgkGKyYACIWySfUB1y1Q4ShQVOdFz65Rl2iYyKzWGVgc4pYuLg/0O8J3W51qLwhuGU9h3tHsuizKfcG7e3B1S5LqbwE4lAp/qBd+eHkdDm/89UFXMMqCy3w17sgaQx8= 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 1607457673830514.8051302591812; Tue, 8 Dec 2020 12:01:13 -0800 (PST) Received: from list by lists.xenproject.org with outflank-mailman.47770.84622 (Exim 4.92) (envelope-from ) id 1kmjAM-0005A2-NT; Tue, 08 Dec 2020 20:00:54 +0000 Received: by outflank-mailman (output) from mailman id 47770.84622; Tue, 08 Dec 2020 20:00:54 +0000 Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAL-00059Y-Oc; Tue, 08 Dec 2020 20:00:53 +0000 Received: by outflank-mailman (input) for mailman id 47770; Tue, 08 Dec 2020 20:00:46 +0000 Received: from mail.xenproject.org ([104.130.215.37]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAE-0004pY-01 for xen-devel@lists.xenproject.org; Tue, 08 Dec 2020 20:00:46 +0000 Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kmjAD-00086a-3y; Tue, 08 Dec 2020 20:00:45 +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 1kmihK-0001p0-Hr; Tue, 08 Dec 2020 19:30:54 +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=Content-Transfer-Encoding:MIME-Version:References: In-Reply-To:Message-Id:Date:Subject:Cc:To:From; bh=UhlxfGmI/aEuEJYbZvO+wCWpWg3W+k9Y3YHBgam9bbQ=; b=F/WcsDkRt8mlAXrlFtOscwsnHx rUnmrIHMRw331u/FS2GTWJ3Eo7GPC0/q0ojoisBBfAWMxsE6mnNoCLgR/m7cJja0IvJrMATQdqq+f GxFm5tv93YUJIgH8P+4nzE0iwh/w2rZHIP1t/W3tiW99Q8P62p9280RIqnsyHQ6sb/Io=; From: Paul Durrant To: xen-devel@lists.xenproject.org Cc: Paul Durrant , Oleksandr Andrushchenko , Wei Liu , Ian Jackson Subject: [PATCH v6 15/25] docs/man: extract documentation of PCI_SPEC_STRING from the xl.cfg manpage... Date: Tue, 8 Dec 2020 19:30:23 +0000 Message-Id: <20201208193033.11306-16-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 Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @xen.org) Content-Type: text/plain; charset="utf-8" From: Paul Durrant ... and put it into a new xl-pci-configuration(5) manpage, akin to the xl-network-configration(5) and xl-disk-configuration(5) manpages. This patch moves the content of the section verbatim. A subsequent patch will improve the documentation, once it is in its new location. Signed-off-by: Paul Durrant Reviewed-by: Oleksandr Andrushchenko Acked-by: Wei Liu --- Cc: Ian Jackson --- docs/man/xl-pci-configuration.5.pod | 78 +++++++++++++++++++++++++++++ docs/man/xl.cfg.5.pod.in | 68 +------------------------ 2 files changed, 79 insertions(+), 67 deletions(-) create mode 100644 docs/man/xl-pci-configuration.5.pod diff --git a/docs/man/xl-pci-configuration.5.pod b/docs/man/xl-pci-configur= ation.5.pod new file mode 100644 index 000000000000..72a27bd95dec --- /dev/null +++ b/docs/man/xl-pci-configuration.5.pod @@ -0,0 +1,78 @@ +=3Dencoding utf8 + +=3Dhead1 NAME + +xl-pci-configuration - XL PCI Configuration Syntax + +=3Dhead1 SYNTAX + +This document specifies the format for B which is used by +the L pci configuration option, and related L commands. + +Each B has the form of +B<[DDDD:]BB:DD.F[@VSLOT],KEY=3DVALUE,KEY=3DVALUE,...> where: + +=3Dover 4 + +=3Ditem B<[DDDD:]BB:DD.F> + +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. + +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 B<@VSLOT> + +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>. + +=3Ditem B + +By default pciback only allows PV guests to write "known safe" values +into PCI configuration space, likewise QEMU (both qemu-xen and +qemu-xen-traditional) imposes the same constraint on HVM guests. +However, many devices require writes to other areas of the configuration s= pace +in order to operate properly. This option tells the backend (pciback or Q= EMU) +to allow all writes to the PCI configuration space of this device by this +domain. + +B it gives the guest much +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. + +=3Ditem B + +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 +function when this option is enabled. Therefore the default is false (0). + +=3Ditem B + +Tells B to automatically attempt to re-assign a device to +pciback if it is not already assigned. + +B If you set this option, B 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. + +=3Ditem B + +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). + +=3Ditem B + +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". + +Note: this would override global B option. + +=3Dback diff --git a/docs/man/xl.cfg.5.pod.in b/docs/man/xl.cfg.5.pod.in index 12201a7e5461..c8e017f950de 100644 --- a/docs/man/xl.cfg.5.pod.in +++ b/docs/man/xl.cfg.5.pod.in @@ -1101,73 +1101,7 @@ option is valid only when the B option i= s specified. =3Ditem B =20 Specifies the host PCI devices to passthrough to this guest. -Each B has the form of -B<[DDDD:]BB:DD.F[@VSLOT],KEY=3DVALUE,KEY=3DVALUE,...> where: - -=3Dover 4 - -=3Ditem B<[DDDD:]BB:DD.F> - -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. - -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 B<@VSLOT> - -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>. - -=3Ditem B - -By default pciback only allows PV guests to write "known safe" values -into PCI configuration space, likewise QEMU (both qemu-xen and -qemu-xen-traditional) imposes the same constraint on HVM guests. -However, many devices require writes to other areas of the configuration s= pace -in order to operate properly. This option tells the backend (pciback or Q= EMU) -to allow all writes to the PCI configuration space of this device by this -domain. - -B it gives the guest much -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. - -=3Ditem B - -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 -function when this option is enabled. Therefore the default is false (0). - -=3Ditem B - -Tells B to automatically attempt to re-assign a device to -pciback if it is not already assigned. - -B If you set this option, B 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. - -=3Ditem B - -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). - -=3Ditem B - -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". - -Note: this would override global B option. - -=3Dback +See L for more details. =20 =3Ditem B =20 --=20 2.20.1