From nobody Sat Apr 18 10:53:34 2026 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by smtp.lore.kernel.org (Postfix) with ESMTP id 62761CCA47B for ; Thu, 14 Jul 2022 12:03:47 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S238393AbiGNMDq (ORCPT ); Thu, 14 Jul 2022 08:03:46 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:45318 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230016AbiGNMDm (ORCPT ); Thu, 14 Jul 2022 08:03:42 -0400 Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id E35D31AE for ; Thu, 14 Jul 2022 05:03:32 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1657800212; h=from:from: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; bh=wAxz9tvWBXP7vb3lbaEzVBejhbAljYzNf3UGKYGM0hM=; b=M9XNxA/GeRPEQLsyYFNRE/wArUjJKlKj3toQqRoLEIgEAyasrxp/4UqM80ZBUXNPFxFsQ1 zIsE6HBayZfpH7140AJgNZoVeh809Vut/fWfjTdqXpAThLX36MmhTrTmlEiJ3WiN+qf5LR 0vV45gxsMeJFwdSMxMzFmuHihveIN5s= Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-29-Z5XlF72MMByeMNnpFn95vw-1; Thu, 14 Jul 2022 08:03:30 -0400 X-MC-Unique: Z5XlF72MMByeMNnpFn95vw-1 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.rdu2.redhat.com [10.11.54.6]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 82206811E75; Thu, 14 Jul 2022 12:03:30 +0000 (UTC) Received: from virtlab701.virt.lab.eng.bos.redhat.com (virtlab701.virt.lab.eng.bos.redhat.com [10.19.152.228]) by smtp.corp.redhat.com (Postfix) with ESMTP id 698B92166B26; Thu, 14 Jul 2022 12:03:30 +0000 (UTC) From: Paolo Bonzini To: linux-kernel@vger.kernel.org, kvm@vger.kernel.org Subject: [PATCH] Documentation: kvm: clarify histogram units Date: Thu, 14 Jul 2022 08:03:30 -0400 Message-Id: <20220714120330.1410308-2-pbonzini@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 2.78 on 10.11.54.6 Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Type: text/plain; charset="utf-8" In the case of histogram statistics, the values are always sample counts; the unit instead applies to the bucket range. For example, halt_poll_success_hist is a nanosecond statistic because the buckets are for 0ns, 1ns, 2-3ns, 4-7ns etc. There isn't really any other sensible interpretation, but clarify this anyway in the Documentation. Signed-off-by: Paolo Bonzini --- Documentation/virt/kvm/api.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Documentation/virt/kvm/api.rst b/Documentation/virt/kvm/api.rst index 48bf6e49a7de..6e090fb96a0e 100644 --- a/Documentation/virt/kvm/api.rst +++ b/Documentation/virt/kvm/api.rst @@ -5703,14 +5703,13 @@ Bits 0-3 of ``flags`` encode the type: by the ``hist_param`` field. The range of the Nth bucket (1 <=3D N < `= `size``) is [``hist_param``*(N-1), ``hist_param``*N), while the range of the la= st bucket is [``hist_param``*(``size``-1), +INF). (+INF means positive in= finity - value.) The bucket value indicates how many samples fell in the bucket= 's range. + value.) * ``KVM_STATS_TYPE_LOG_HIST`` The statistic is reported as a logarithmic histogram. The number of buckets is specified by the ``size`` field. The range of the first buc= ket is [0, 1), while the range of the last bucket is [pow(2, ``size``-2), +IN= F). Otherwise, The Nth bucket (1 < N < ``size``) covers - [pow(2, N-2), pow(2, N-1)). The bucket value indicates how many sample= s fell - in the bucket's range. + [pow(2, N-2), pow(2, N-1)). =20 Bits 4-7 of ``flags`` encode the unit: =20 @@ -5731,6 +5730,10 @@ Bits 4-7 of ``flags`` encode the unit: statistics can be linear histograms (with two buckets) but not logarit= hmic histograms. =20 +Note that, in the case of histograms, the unit applies to the bucket +ranges, while the bucket value indicates how many samples fell in the +bucket's range. + Bits 8-11 of ``flags``, together with ``exponent``, encode the scale of the unit: =20 @@ -5752,7 +5755,7 @@ the corresponding statistics data. =20 The ``bucket_size`` field is used as a parameter for histogram statistics = data. It is only used by linear histogram statistics data, specifying the size o= f a -bucket. +bucket in the unit expressed by bits 4-11 of ``flags`` together with ``exp= onent``. =20 The ``name`` field is the name string of the statistics data. The name str= ing starts at the end of ``struct kvm_stats_desc``. The maximum length includ= ing --=20 2.31.1