From patchwork Fri Dec 9 16:17:14 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Cedric Bosdonnat X-Patchwork-Id: 9468601 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id B3B32607D8 for ; Fri, 9 Dec 2016 16:20:04 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id A25E32864E for ; Fri, 9 Dec 2016 16:20:04 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 975E528650; Fri, 9 Dec 2016 16:20:04 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-4.2 required=2.0 tests=BAYES_00,LOTS_OF_MONEY, RCVD_IN_DNSWL_MED autolearn=ham version=3.3.1 Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 9B9E228652 for ; Fri, 9 Dec 2016 16:19:56 +0000 (UTC) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrZ-0008Ae-0X; Fri, 09 Dec 2016 16:17:33 +0000 Received: from mail6.bemta6.messagelabs.com ([193.109.254.103]) by lists.xenproject.org with esmtp (Exim 4.84_2) (envelope-from ) id 1cFNrX-00088n-SV for xen-devel@lists.xen.org; Fri, 09 Dec 2016 16:17:31 +0000 Received: from [85.158.143.35] by server-2.bemta-6.messagelabs.com id 00/C1-12366-B19DA485; Fri, 09 Dec 2016 16:17:31 +0000 X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFprLIsWRWlGSWpSXmKPExsVyuP0uq67UTa8 Ig4ubpSyWfFzM4sDocXT3b6YAxijWzLyk/IoE1oz3bZNZCj7ZViw9O5e9gXGicRcjF4eQwBJG ibONf5m7GDk52ATsJbr+HGUCsUUEpCWufb7MCFLELLCZUeL85IksIAlhATuJ05PegTWwCKhK/ Pk6EyzOK2Ap8XddFyuILSEgL7Gr7SKYzQkUv3T2CzuILSRgIbFk4XlWiHpBiZMznwD1cgAtUJ dYP08IJMwM1Nq8dTbzBEbeWUiqZiFUzUJStYCReRWjRnFqUVlqka6hoV5SUWZ6RkluYmaOrqG BmV5uanFxYnpqTmJSsV5yfu4mRmBQMQDBDsZPywIOMUpyMCmJ8hYzeUUI8SXlp1RmJBZnxBeV 5qQWH2KU4eBQkuC9fx0oJ1iUmp5akZaZAwxvmLQEB4+SCK8KSJq3uCAxtzgzHSJ1ilGXY9qzx U+ZhFjy8vNSpcR5r4MUCYAUZZTmwY2AxdolRlkpYV5GoKOEeApSi3IzS1DlXzGKczAqCfM+AJ nCk5lXArfpFdARTEBHzLvhDnJESSJCSqqBcU1sqtzqaQz7frofklti9lXshA1niUdVhOrac6f 9uw+sD43S8++ZFVGzLOfCl5QrnOt4Ww4VVnTdm8W5/l7CSqnUYw/Xz6r415UpyLUyW32Nvtrk uy8T439I2STzRHW8/XZq3gtXPaYHq548rLa8YfzmcMEOpmXMsz58224/zXXHxyfhc/3mNyqxF GckGmoxFxUnAgAOa/9JsAIAAA== X-Env-Sender: cbosdonnat@suse.com X-Msg-Ref: server-16.tower-21.messagelabs.com!1481300249!43015214!1 X-Originating-IP: [195.135.221.5] X-SpamReason: No, hits=0.0 required=7.0 tests= X-StarScan-Received: X-StarScan-Version: 9.1.1; banners=-,-,- X-VirusChecked: Checked Received: (qmail 41535 invoked from network); 9 Dec 2016 16:17:30 -0000 Received: from smtp.nue.novell.com (HELO smtp.nue.novell.com) (195.135.221.5) by server-16.tower-21.messagelabs.com with DHE-RSA-AES256-GCM-SHA384 encrypted SMTP; 9 Dec 2016 16:17:30 -0000 Received: from laptop.vms (mhy71-2-88-167-63-197.fbx.proxad.net [88.167.63.197]) by smtp.nue.novell.com with ESMTP (TLS encrypted); Fri, 09 Dec 2016 17:17:28 +0100 From: =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= To: xen-devel@lists.xen.org Date: Fri, 9 Dec 2016 17:17:14 +0100 Message-Id: <20161209161714.23866-12-cbosdonnat@suse.com> X-Mailer: git-send-email 2.11.0 In-Reply-To: <20161209161714.23866-1-cbosdonnat@suse.com> References: <20161209161714.23866-1-cbosdonnat@suse.com> MIME-Version: 1.0 Cc: Andrew Cooper , Ian Jackson , Wei Liu , =?UTF-8?q?C=C3=A9dric=20Bosdonnat?= Subject: [Xen-devel] [PATCH 11/11] docs: convert tscmode.txt into man page X-BeenThere: xen-devel@lists.xen.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xen.org Sender: "Xen-devel" X-Virus-Scanned: ClamAV using ClamSMTP tscmode.txt is referenced in xl.cfg(5). Convert it into a pod formatted man page. Signed-off-by: Cédric Bosdonnat Acked-by: Wei Liu --- docs/INDEX | 1 - docs/{misc/tscmode.txt => man/tscmode.pod.7} | 109 ++++++++++++++++++--------- docs/man/xl.cfg.pod.5.in | 4 +- 3 files changed, 76 insertions(+), 38 deletions(-) rename docs/{misc/tscmode.txt => man/tscmode.pod.7} (89%) diff --git a/docs/INDEX b/docs/INDEX index 66cc82b78c..868ab1fc1d 100644 --- a/docs/INDEX +++ b/docs/INDEX @@ -12,7 +12,6 @@ misc/xen-command-line Xen Hypervisor Command Line Options misc/crashdb Xen crash debugger notes misc/grant-tables A Rough Introduction to Using Grant Tables misc/kexec_and_kdump Kexec and Kdump for Xen -misc/tscmode TSC Mode HOWTO misc/xenstore Xenstore protocol specification misc/xenstore-paths Xenstore path documentation misc/distro_mapping Distro Directory Layouts diff --git a/docs/misc/tscmode.txt b/docs/man/tscmode.pod.7 similarity index 89% rename from docs/misc/tscmode.txt rename to docs/man/tscmode.pod.7 index 01ee060598..0da57e5327 100644 --- a/docs/misc/tscmode.txt +++ b/docs/man/tscmode.pod.7 @@ -1,7 +1,4 @@ -TSC_MODE HOW-TO -by: Dan Magenheimer - -OVERVIEW +=head1 OVERVIEW As of Xen 4.0, a new config option called tsc_mode may be specified for each domain. The default for tsc_mode handles the vast majority @@ -16,16 +13,29 @@ equally to both the OS and ALL apps that are running on this domain, now or in the future. Key questions to be answered for the OS and/or each application are: -- Does the OS/app use the rdtsc instruction at all? (We will explain below - how to determine this.) -- At what frequency is the rdtsc instruction executed by either the OS - or any running apps? If the sum exceeds about 10,000 rdtsc instructions - per second per processor, we call this a "high-TSC-frequency" - OS/app/environment. (This is relatively rare, and developers of OS's - and apps that are high-TSC-frequency are usually aware of it.) -- If the OS/app does use rdtsc, will it behave incorrectly if "time goes - backwards" or if the frequency of the TSC suddenly changes? If so, - we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient". + +=over 4 + +=item * + +Does the OS/app use the rdtsc instruction at all? +(We will explain below how to determine this.) + +=item * + +At what frequency is the rdtsc instruction executed by either the OS +or any running apps? If the sum exceeds about 10,000 rdtsc instructions +per second per processor, we call this a "high-TSC-frequency" +OS/app/environment. (This is relatively rare, and developers of OS's +and apps that are high-TSC-frequency are usually aware of it.) + +=item * + +If the OS/app does use rdtsc, will it behave incorrectly if "time goes +backwards" or if the frequency of the TSC suddenly changes? If so, +we call this a "TSC-sensitive" app or OS; otherwise it is "TSC-resilient". + +=back This last is the US$64,000 question as it may be very difficult (or, for legacy apps, even impossible) to predict all possible @@ -46,38 +56,63 @@ an intelligent default but allows system administrator's to adjust how rdtsc instructions are executed differently for different domains. The non-default choices for tsc_mode are: -- tsc_mode=1 (always emulate). All rdtsc instructions are emulated; - this is the best choice when TSC-sensitive apps are running and - it is necessary to understand worst-case performance degradation - for a specific hardware environment. -- tsc_mode=2 (never emulate). This is the same as prior to Xen 4.0 - and is the best choice if it is certain that all apps running in - this VM are TSC-resilient and highest performance is required. -- tsc_mode=3 (PVRDTSCP). High-TSC-frequency apps may be paravirtualized - (modified) to obtain both correctness and highest performance; any - unmodified apps must be TSC-resilient. - -If tsc_mode is left unspecified (or set to tsc_mode=0), a hybrid + +=over 4 + +=item * B (always emulate). + +All rdtsc instructions are emulated; this is the best choice when +TSC-sensitive apps are running and it is necessary to understand +worst-case performance degradation for a specific hardware environment. + +=item * B (never emulate). + +This is the same as prior to Xen 4.0 and is the best choice if it +is certain that all apps running in this VM are TSC-resilient and +highest performance is required. + +=item * B (PVRDTSCP). + +High-TSC-frequency apps may be paravirtualized (modified) to +obtain both correctness and highest performance; any unmodified +apps must be TSC-resilient. + +=back + +If tsc_mode is left unspecified (or set to B), a hybrid algorithm is utilized to ensure correctness while providing the best performance possible given: -- the requirement of correctness, -- the underlying hardware, and -- whether or not the VM has been saved/restored/migrated + +=over 4 + +=item * + +the requirement of correctness, + +=item * + +the underlying hardware, and + +=item * + +whether or not the VM has been saved/restored/migrated To understand this in more detail, the rest of this document must be read. -DETERMINING RDTSC FREQUENCY +=back + +=head1 DETERMINING RDTSC FREQUENCY To determine the frequency of rdtsc instructions that are emulated, an "xm" command can be used by a privileged user of domain0. The command: -# xm debug-key s; xm dmesg | tail + # xm debug-key s; xm dmesg | tail provides information about TSC usage in each domain where TSC emulation is currently enabled. -TSC HISTORY +=head1 TSC HISTORY To understand tsc_mode completely, some background on TSC is required: @@ -214,7 +249,7 @@ then restored 30 seconds later, TSC is only guaranteed to be greater than or equal to 1001, not precisely 1030. This has some OS implications as will be seen in the next section. -TSC INVARIANT BIT and NO_MIGRATE +=head1 TSC INVARIANT BIT and NO_MIGRATE Related to TSC emulation, the "TSC Invariant" bit is architecturally defined in a cpuid bit on the most recent x86 processors. If set, TSC invariance @@ -251,7 +286,7 @@ decisions based on that bit. This is still an unsolved problem, though a workaround exists as part of the PVRDTSCP tsc_mode for apps that can be modified. -MORE ON PVRDTSCP +=head1 MORE ON PVRDTSCP Paravirtualized OS's use the "pvclock" algorithm to manage the passing of time. This sophisticated algorithm obtains information from a memory @@ -298,7 +333,7 @@ While pvrtscp is too complex for most apps, certain enterprise TSC-sensitive high-TSC-frequency apps may find it useful to obtain a significant performance gain. -Hardware TSC Scaling +=head1 HARDWARE TSC SCALING Intel VMX TSC scaling and AMD SVM TSC ratio allow the guest TSC read by guest rdtsc/p increasing in a different frequency than the host @@ -318,3 +353,7 @@ executed natively before and after migration. For above HVM container in PVRDTSCP mode (tsc_mode=3), if the destination host does not support rdtscp, the guest rdtscp instruction will be emulated with the guest TSC frequency. + +=head1 AUTHORS + +Dan Magenheimer diff --git a/docs/man/xl.cfg.pod.5.in b/docs/man/xl.cfg.pod.5.in index 0dac6f1d9a..de6c5edb99 100644 --- a/docs/man/xl.cfg.pod.5.in +++ b/docs/man/xl.cfg.pod.5.in @@ -1463,7 +1463,7 @@ determined in the similar way to that of B TSC mode. =back -Please see F for more information on this option. +Please see L for more information on this option. =item B @@ -2033,7 +2033,7 @@ natively or via hardware backwards compatibility support. =item L -=item F +=item L =back