From nobody Mon May 6 13:02:57 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) client-ip=207.211.31.120; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-1.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 207.211.31.120 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com Return-Path: Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [207.211.31.120]) by mx.zohomail.com with SMTPS id 1582058857236483.12857075159343; Tue, 18 Feb 2020 12:47:37 -0800 (PST) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-267-sony8LrMNASWiO7JntDWxw-1; Tue, 18 Feb 2020 15:47:33 -0500 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 10A9AA0CC2; Tue, 18 Feb 2020 20:47:26 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id F37F88CCC5; Tue, 18 Feb 2020 20:47:23 +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 78A2D35AF6; Tue, 18 Feb 2020 20:47:20 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 01IKlICE016858 for ; Tue, 18 Feb 2020 15:47:18 -0500 Received: by smtp.corp.redhat.com (Postfix) id C0E9160BF7; Tue, 18 Feb 2020 20:47:18 +0000 (UTC) Received: from kinshicho.usersys.redhat.com (unknown [10.43.2.246]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 4568660BE1 for ; Tue, 18 Feb 2020 20:47:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1582058856; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=C4vIa0Kmtp1awRh0q9hBlMnrgqZ+ItJVntPtCwIXJFY=; b=fyV/Xongn6TYsSOPDsHfLwRbv8B0r10x6DnVj9ajW5heclvPFLywUAJK32HN0oGJjs3JWq Tc1Q71q1bAfUr+SpnYNKlbIJbe5s1dquo3wPmmRH0XNN1mMHu4OvdGXNSMp5fquTmR8iMG QkFttaxmah0TzvWE2V4sGzktNJpVkgQ= From: Andrea Bolognani To: libvir-list@redhat.com Subject: [libvirt PATCH] docs: Expand documentation for the tickpolicy timer attribute Date: Tue, 18 Feb 2020 21:47:13 +0100 Message-Id: <20200218204713.299986-1-abologna@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-loop: libvir-list@redhat.com 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: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-MC-Unique: sony8LrMNASWiO7JntDWxw-1 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" The current documentation is fairly terse and not easy to decode for someone who's not intimately familiar with the inner workings of timer devices. Expand on it by providing a somewhat verbose description of what behavior each policy will result in, as seen from both the guest OS and host point of view. This is lifted directly from QEMU commit commit 2a7d957596786404c4ed16b089273de95a9580ad Author: Andrea Bolognani Date: Tue Feb 11 19:37:44 2020 +0100 qapi: Expand documentation for LostTickPolicy v4.2.0-1442-g2a7d957596 The original text also matched word for word the documentation found in QEMU. Signed-off-by: Andrea Bolognani Reviewed-by: Michal Privoznik --- docs/formatdomain.html.in | 32 +++++++++++++++++++++----------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index f4af65f13f..4fef2a0a97 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -2487,26 +2487,36 @@

The tickpolicy attribute determines what happens when QEMU misses a deadline for injecting a - tick to the guest: + tick to the guest. This can happen, for example, because the + guest was paused.

delay
-
Continue to deliver ticks at the normal rate. - The guest time will be delayed due to the late - tick
+
Continue to deliver ticks at the normal rate. The guest = OS + will not notice anything is amiss, as from its point of vi= ew + time will have continued to flow normally. The time in the + guest should now be behind the time in the host by exactly + the amount of time during which ticks have been missed.
catchup
-
Deliver ticks at a higher rate to catch up - with the missed tick. The guest time should - not be delayed once catchup is complete.
+
Deliver ticks at a higher rate to catch up with the miss= ed + ticks. The guest OS will not notice anything is amiss, as + from its point of view time will have continued to flow + normally. Once the timer has managed to catch up with all + the missing ticks, the time in the guest and in the host + should match.
merge
Merge the missed tick(s) into one tick and inject. The guest time may be delayed, depending on how the OS reacts to the merging of ticks
discard
-
Throw away the missed tick(s) and continue - with future injection normally. The guest time - may be delayed, unless the OS has explicit - handling of lost ticks
+
Throw away the missed ticks and continue with future + injection normally. The guest OS will see the timer jump + ahead by a potentially quite significant amount all at onc= e, + as if the intervening chunk of time had simply not existed; + needless to say, such a sudden jump can easily confuse a + guest OS which is not specifically prepared to deal with i= t. + Assuming the guest OS can deal correctly with the time jum= p, + the time in the guest and in the host should now match.

If the policy is "catchup", there can be further details in the catchup sub-element.

--=20 2.24.1