From nobody Sat Feb 7 06:48:04 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1531908561731989.0845490124046; Wed, 18 Jul 2018 03:09:21 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.25]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 268F6308A950; Wed, 18 Jul 2018 10:09:19 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D05EC2010CE0; Wed, 18 Jul 2018 10:09:17 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id D054918037EF; Wed, 18 Jul 2018 10:09:16 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id w6IA9ELj015904 for ; Wed, 18 Jul 2018 06:09:14 -0400 Received: by smtp.corp.redhat.com (Postfix) id 165D121568A0; Wed, 18 Jul 2018 10:09:14 +0000 (UTC) Received: from sequoia.brq.redhat.com (unknown [10.43.2.215]) by smtp.corp.redhat.com (Postfix) with ESMTP id 873092156899 for ; Wed, 18 Jul 2018 10:09:13 +0000 (UTC) From: Katerina Koukiou To: libvir-list@redhat.com Date: Wed, 18 Jul 2018 12:09:12 +0200 Message-Id: <20180718100912.17205-1-kkoukiou@redhat.com> X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] docs: formatdomain: unify naming for CPUs/vCPUs X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.84 on 10.5.11.25 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.41]); Wed, 18 Jul 2018 10:09:20 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" CPU is an acronym and should be written in uppercase when part of plain text and not refering to an element. Signed-off-by: Katerina Koukiou Reviewed-by: Erik Skultety --- As asked in the review here https://www.redhat.com/archives/libvir-list/2018-July/msg01093.html docs/formatdomain.html.in | 84 +++++++++++++++++++-------------------- 1 file changed, 42 insertions(+), 42 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index b00971a945..d08ede9ab5 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -631,45 +631,45 @@
vcpus
- The vcpus element allows to control state of individual vcpus. + The vcpus element allows to control state of individual vCPUs. =20 The id attribute specifies the vCPU id as used by lib= virt - in other places such as vcpu pinning, scheduler information and NU= MA - assignment. Note that the vcpu ID as seen in the guest may differ = from - libvirt ID in certain cases. Valid IDs are from 0 to the maximum v= cpu + in other places such as vCPU pinning, scheduler information and NU= MA + assignment. Note that the vCPU ID as seen in the guest may differ = from + libvirt ID in certain cases. Valid IDs are from 0 to the maximum v= CPU count as set by the vcpu element minus 1. =20 The enabled attribute allows to control the state of = the - vcpu. Valid values are yes and no. + vCPU. Valid values are yes and no. =20 - hotpluggable controls whether given vcpu can be hotpl= ugged - and hotunplugged in cases when the cpu is enabled at boot. Note th= at - all disabled vcpus must be hotpluggable. Valid values are + hotpluggable controls whether given vCPU can be hotpl= ugged + and hotunplugged in cases when the CPU is enabled at boot. Note th= at + all disabled vCPUs must be hotpluggable. Valid values are yes and no. =20 - order allows to specify the order to add the online v= cpus. - For hypervisors/platforms that require to insert multiple vcpus at= once - the order may be duplicated across all vcpus that need to be - enabled at once. Specifying order is not necessary, vcpus are then + order allows to specify the order to add the online v= CPUs. + For hypervisors/platforms that require to insert multiple vCPUs at= once + the order may be duplicated across all vCPUs that need to be + enabled at once. Specifying order is not necessary, vCPUs are then added in an arbitrary order. If order info is used, it must be use= d for - all online vcpus. Hypervisors may clear or update ordering informa= tion + all online vCPUs. Hypervisors may clear or update ordering informa= tion during certain operations to assure valid configuration. =20 - Note that hypervisors may create hotpluggable vcpus differently fr= om - boot vcpus thus special initialization may be necessary. + Note that hypervisors may create hotpluggable vCPUs differently fr= om + boot vCPUs thus special initialization may be necessary. =20 - Hypervisors may require that vcpus enabled on boot which are not + Hypervisors may require that vCPUs enabled on boot which are not hotpluggable are clustered at the beginning starting with ID 0. It= may - be also required that vcpu 0 is always present and non-hotpluggabl= e. + be also required that vCPU 0 is always present and non-hotpluggabl= e. =20 - Note that providing state for individual cpus may be necessary to = enable + Note that providing state for individual CPUs may be necessary to = enable support of addressable vCPU hotplug and this feature may not be supported by all hypervisors. =20 - For QEMU the following conditions are required. Vcpu 0 needs to be - enabled and non-hotpluggable. On PPC64 along with it vcpus that ar= e in - the same core need to be enabled as well. All non-hotpluggable cpus - present at boot need to be grouped after vcpu 0. + For QEMU the following conditions are required. vCPU 0 needs to be + enabled and non-hotpluggable. On PPC64 along with it vCPUs that ar= e in + the same core need to be enabled as well. All non-hotpluggable CPUs + present at boot need to be grouped after vCPU 0. Since 2.2.0 (QEMU only)
@@ -774,11 +774,11 @@
vcpupin
The optional vcpupin element specifies which of host's - physical CPUs the domain VCPU will be pinned to. If this is omitte= d, + physical CPUs the domain vCPU will be pinned to. If this is omitte= d, and attribute cpuset of element vcpu is not specified, the vCPU is pinned to all the physical CPUs by defa= ult. It contains two required attributes, the attribute vcpu - specifies vcpu id, and the attribute cpuset is same as + specifies vCPU id, and the attribute cpuset is same as attribute cpuset of element vcpu. (NB: Only qemu driver support) Since 0.9.0 @@ -786,7 +786,7 @@
emulatorpin
The optional emulatorpin element specifies which of = host - physical CPUs the "emulator", a subset of a domain not including = vcpu + physical CPUs the "emulator", a subset of a domain not including = vCPU or iothreads will be pinned to. If this is omitted, and attribute cpuset of element vcpu is not specified, "emulator" is pinned to all the physical CPUs by default. It cont= ains @@ -820,7 +820,7 @@
period
The optional period element specifies the enforcement - interval(unit: microseconds). Within period, each vcp= u of + interval(unit: microseconds). Within period, each vCP= U of the domain will not be allowed to consume more than quota worth of runtime. The value should be in range [1000, 1000000]. A = period with value 0 means no value. @@ -835,7 +835,7 @@ vCPU threads, which means that it is not bandwidth controlled. The= value should be in range [1000, 18446744073709551] or less than 0. A quo= ta with value 0 means no value. You can use this feature to ensure th= at all - vcpus run at the same speed. + vCPUs run at the same speed. Only QEMU driver support since 0.9.4, LXC si= nce 0.9.10
@@ -864,7 +864,7 @@
The optional emulator_period element specifies the en= forcement interval(unit: microseconds). Within emulator_period,= emulator - threads(those excluding vcpus) of the domain will not be allowed t= o consume + threads(those excluding vCPUs) of the domain will not be allowed t= o consume more than emulator_quota worth of runtime. The value = should be in range [1000, 1000000]. A period with value 0 means no value. Only QEMU driver support since 0.10.0 @@ -873,9 +873,9 @@
The optional emulator_quota element specifies the max= imum allowed bandwidth(unit: microseconds) for domain's emulator thread= s(those - excluding vcpus). A domain with emulator_quota as any= negative + excluding vCPUs). A domain with emulator_quota as any= negative value indicates that the domain has infinite bandwidth for emulato= r threads - (those excluding vcpus), which means that it is not bandwidth cont= rolled. + (those excluding vCPUs), which means that it is not bandwidth cont= rolled. The value should be in range [1000, 18446744073709551] or less tha= n 0. A quota with value 0 means no value. Only QEMU driver support since 0.10.0 @@ -2131,13 +2131,13 @@ QEMU, the user-configurable extended TSEG feature was unavailabl= e up to and including pc-q35-2.9. Starting with pc-q35-2.10 the feature is available, with default = size - 16 MiB. That should suffice for up to roughly 272 VCPUs, 5 GiB = guest + 16 MiB. That should suffice for up to roughly 272 vCPUs, 5 GiB = guest RAM in total, no hotplug memory range, and 32 GiB of 64-bit PCI = MMIO - aperture. Or for 48 VCPUs, with 1TB of guest RAM, no hotplug DI= MM + aperture. Or for 48 vCPUs, with 1TB of guest RAM, no hotplug DI= MM range, and 32GB of 64-bit PCI MMIO aperture. The values may also= vary based on the loader the VM is using.

- Additional size might be needed for significantly higher VCPU co= unts + Additional size might be needed for significantly higher vCPU co= unts or increased address space (that can be memory, maxMemory, 64-bi= t PCI MMIO aperture size; roughly 8 MiB of TSEG per 1 TiB of address s= pace) which can also be rounded up. @@ -2147,7 +2147,7 @@ documentation of the guest OS or loader (if there is any), or te= st this by trial-and-error changing the value until the VM boots successfully. Yet another guiding value for users might be the = fact - that 48 MiB should be enough for pretty large guests (240 VCPUs = and + that 48 MiB should be enough for pretty large guests (240 vCPUs = and 4TB guest RAM), but it is on purpose not set as default as 48 Mi= B of unavailable RAM might be too much for small guests (e.g. with 51= 2 MiB of RAM). @@ -2425,7 +2425,7 @@ cpu_cycles - the count of cpu cycles (total/elapsed) + the count of CPU cycles (total/elapsed) perf.cpu_cycles @@ -2460,25 +2460,25 @@ stalled_cycles_frontend - the count of stalled cpu cycles in the frontend of the instructi= on + the count of stalled CPU cycles in the frontend of the instructi= on processor pipeline by applications running on the platform perf.stalled_cycles_frontend stalled_cycles_backend - the count of stalled cpu cycles in the backend of the instruction + the count of stalled CPU cycles in the backend of the instruction processor pipeline by applications running on the platform perf.stalled_cycles_backend ref_cpu_cycles - the count of total cpu cycles not affected by CPU frequency scal= ing + the count of total CPU cycles not affected by CPU frequency scal= ing by applications running on the platform perf.ref_cpu_cycles cpu_clock - the count of cpu clock time, as measured by a monotonic + the count of CPU clock time, as measured by a monotonic high-resolution per-CPU timer, by applications running on the platform perf.cpu_clock @@ -2505,7 +2505,7 @@ cpu_migrations - the count of cpu migrations, that is, where the process + the count of CPU migrations, that is, where the process moved from one logical processor to another, by applications running on the platform perf.cpu_migrations @@ -5621,8 +5621,8 @@ qemu-kvm -net nic,model=3D? /dev/null The resulting difference, according to the qemu developer who added the option is: "bh makes tx more asynchronous and reduces latency, but potentially causes more processor bandwidth - contention since the cpu doing the tx isn't necessarily the - cpu where the guest generated the packets."

+ contention since the CPU doing the tx isn't necessarily the + CPU where the guest generated the packets."

=20 In general you should leave this option alone, unless you are very certain you know what you are doing. --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list