From: Michal Privoznik <mprivozn@redhat.com>
Date: Mon, 3 Jan 2022 14:56:43 +0000 (+0100)
Subject: docs: Clarify 'burst' units for QoS
X-Git-Tag: v8.0.0-rc1~62
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f3b422d9cc49805df6ff24d60859b44f02eb674c;p=thirdparty%2Flibvirt.git

docs: Clarify 'burst' units for QoS

The burst attribute for bandwidth specifies how much bytes can be
transmitted in a single burst. Therefore, the unit is in
multiples of 1024 (thus kibibytes) not SI-like 1000. It has
always been like that.

The 'tc' output is still confusing though, for instance:

  # tc class add dev $DEV parent 1: classid 1:1 htb rate 1000kbps burst 2097152
  # tc class show dev vnet2
  class htb 1:1 root rate 8Mbit ceil 8Mbit burst 2Mb cburst 1600b

Please note that 2097152 = 2*1024*1024. Even the man page is
confusing. From tc(8):

  kb or k        Kilobytes
  mb or m        Megabytes

But I guess this is because 'tc' predates IEC standardisation of
binary multiples and thus can't change without breaking scripts
parsing its output.

And while at it, adjust _virNetDevBandwidthRate struct member
description, to make it obvious which members use SI/IEC units.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
Reviewed-by: Martin Kletzander <mkletzan@redhat.com>
---

diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index b1b2391f43..fad43f77ea 100644
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -634,7 +634,7 @@
           </dd>
           <dt><code>burst</code></dt>
           <dd>
-          Optional attribute which specifies the amount of kilobytes that
+          Optional attribute which specifies the amount of kibibytes that
           can be transmitted in a single burst at <code>peak</code> speed.
           </dd>
           <dt><code>floor</code></dt>
diff --git a/src/util/virnetdevbandwidth.h b/src/util/virnetdevbandwidth.h
index 3d520721f6..c82029fc0f 100644
--- a/src/util/virnetdevbandwidth.h
+++ b/src/util/virnetdevbandwidth.h
@@ -23,10 +23,10 @@
 
 typedef struct _virNetDevBandwidthRate virNetDevBandwidthRate;
 struct _virNetDevBandwidthRate {
-    unsigned long long average;  /* kbytes/s */
-    unsigned long long peak;     /* kbytes/s */
-    unsigned long long floor;    /* kbytes/s */
-    unsigned long long burst;    /* kbytes */
+    unsigned long long average;  /* kilobytes/s */
+    unsigned long long peak;     /* kilobytes/s */
+    unsigned long long floor;    /* kilobytes/s */
+    unsigned long long burst;    /* kibibytes */
 };
 
 typedef struct _virNetDevBandwidth virNetDevBandwidth;