docs: use correct terminology for 1024 bytes

Yes, I like kilobytes better than kibibytes (when I say kilobytes,
I generally mean 1024).  But since the term is ambiguous, it can't
hurt to say what we mean, by using both the correct name and
calling out the numeric equivalent.

* src/libvirt.c (virDomainGetMaxMemory, virDomainSetMaxMemory)
(virDomainSetMemory, virDomainSetMemoryFlags)
(virNodeGetFreeMemory): Tweak wording.
* docs/formatdomain.html.in: Likewise.
* docs/formatstorage.html.in: Likewise.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 42f38d30b05c7eddf06b64d52e0d777ddfb0a066..b7cfb388a00a08f25014460b812f0ad31fa4df8f 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -424,7 +424,7 @@
     <dl>
       <dt><code>memory</code></dt>
       <dd>The maximum allocation of memory for the guest at boot time.
-        The units for this value are kilobytes (i.e. blocks of 1024 bytes)</dd>
+        The units for this value are kibibytes (i.e. blocks of 1024 bytes)</dd>
       <dt><code>currentMemory</code></dt>
       <dd>The actual allocation of memory for the guest. This value can
         be less than the maximum allocation, to allow for ballooning
@@ -480,21 +480,21 @@
         determine so one needs guess and try.</dd>
       <dt><code>hard_limit</code></dt>
       <dd> The optional <code>hard_limit</code> element is the maximum memory
-        the guest can use. The units for this value are kilobytes (i.e. blocks
+        the guest can use. The units for this value are kibibytes (i.e. blocks
         of 1024 bytes)</dd>
       <dt><code>soft_limit</code></dt>
       <dd> The optional <code>soft_limit</code> element is the memory limit to
         enforce during memory contention. The units for this value are
-        kilobytes (i.e. blocks of 1024 bytes)</dd>
+        kibibytes (i.e. blocks of 1024 bytes)</dd>
       <dt><code>swap_hard_limit</code></dt>
       <dd> The optional <code>swap_hard_limit</code> element is the maximum
         memory plus swap the guest can use. The units for this value are
-        kilobytes (i.e. blocks of 1024 bytes). This has to be more than
+        kibibytes (i.e. blocks of 1024 bytes). This has to be more than
         hard_limit value provided</dd>
       <dt><code>min_guarantee</code></dt>
       <dd> The optional <code>min_guarantee</code> element is the guaranteed
         minimum memory allocation for the guest. The units for this value are
-        kilobytes (i.e. blocks of 1024 bytes)</dd>
+        kibibytes (i.e. blocks of 1024 bytes)</dd>
     </dl>
 
 
@@ -774,7 +774,7 @@
     <p>
       Each <code>cell</code> element specifies a NUMA cell or a NUMA node.
       <code>cpus</code> specifies the CPU or range of CPUs that are part of
-      the node. <code>memory</code> specifies the node memory in kilobytes
+      the node. <code>memory</code> specifies the node memory in kibibytes
       (i.e. blocks of 1024 bytes). Each cell or node is assigned cellid
       or nodeid in the increasing order starting from 0.
     </p>
@@ -2969,7 +2969,8 @@ qemu-kvm -net nic,model=? /dev/null
         attribute which takes the value "vga", "cirrus", "vmvga", "xen",
         "vbox", or "qxl" (<span class="since">since 0.8.6</span>)
         depending on the hypervisor features available.
-        You can also provide the amount of video memory in kilobytes using
+        You can also provide the amount of video memory in kibibytes
+        (blocks of 1024 bytes) using
         <code>vram</code> and the number of screen with <code>heads</code>.
       </dd>
 

diff --git a/docs/formatstorage.html.in b/docs/formatstorage.html.in
index 0dcf6df031d845c7539cb15de39c2a11606ee98a..acb21faa81445c0932921524a465be71d3dc086a 100644 (file)
--- a/docs/formatstorage.html.in
+++ b/docs/formatstorage.html.in
@@ -234,11 +234,15 @@
         to sparsely allocate a volume. It does not have to honour requests
         for sparse allocation though.<br/>
         <br/>
-        By default this is specified in bytes, but an optional
+        By default this is specified in bytes, but an optional attribute
         <code>unit</code> can be specified to adjust the passed value.
-        Values can be: 'K' (kilobytes), 'M' (megabytes), 'G' (gigabytes),
-        'T' (terabytes), 'P' (petabytes), or 'E' (exabytes).
-        <span class="since">Since 0.4.1</span></dd>
+        Values can be: 'K' (kibibytes, 2<sup>10</sup> or 1024 bytes),
+        'M' (mebibytes, 2<sup>20</sup> or 1,048,576 bytes), 'G'
+        (gibibytes, 2<sup>30</sup> or 1,073,741,824 bytes), 'T'
+        (tebibytes, 2<sup>40</sup> or 1,099,511,627,776 bytes), 'P'
+        (pebibytes, 2<sup>50</sup> or 1,125,899,906,842,624 bytes), or
+        'E' (exbibytes, 2<sup>60</sup> or 1,152,921,504,606,846,976
+        bytes).  <span class="since">Since 0.4.1</span></dd>
       <dt><code>capacity</code></dt>
       <dd>Providing the logical capacity for the volume. This value is
         in bytes by default, but a <code>unit</code> attribute can be

diff --git a/src/libvirt.c b/src/libvirt.c
index c7e4673fe2d3eab608be046775616a90b02f61c9..5de6e6800c6653470c0bd35de8a076bd402b9592 100644 (file)
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -3582,7 +3582,8 @@ error:
  * domain. If domain is NULL, then this get the amount of memory reserved
  * to Domain0 i.e. the domain where the application runs.
  *
- * Returns the memory size in kilobytes or 0 in case of error.
+ * Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in
+ * case of error.
  */
 unsigned long
 virDomainGetMaxMemory(virDomainPtr domain)
@@ -3619,7 +3620,7 @@ error:
 /**
  * virDomainSetMaxMemory:
  * @domain: a domain object or NULL
- * @memory: the memory size in kilobytes
+ * @memory: the memory size in kibibytes (blocks of 1024 bytes)
  *
  * Dynamically change the maximum amount of physical memory allocated to a
  * domain. If domain is NULL, then this change the amount of memory reserved
@@ -3674,7 +3675,7 @@ error:
 /**
  * virDomainSetMemory:
  * @domain: a domain object or NULL
- * @memory: the memory size in kilobytes
+ * @memory: the memory size in kibibytes (blocks of 1024 bytes)
  *
  * Dynamically change the target amount of physical memory allocated to a
  * domain. If domain is NULL, then this change the amount of memory reserved
@@ -3729,7 +3730,7 @@ error:
 /**
  * virDomainSetMemoryFlags:
  * @domain: a domain object or NULL
- * @memory: the memory size in kilobytes
+ * @memory: the memory size in kibibytes (blocks of 1024 bytes)
  * @flags: bitwise-OR of virDomainMemoryModFlags
  *
  * Dynamically change the target amount of physical memory allocated to a
@@ -6684,7 +6685,7 @@ error:
  * @conn: pointer to the hypervisor connection
  *
  * provides the free memory available on the Node
- * Note: most libvirt APIs provide memory sizes in kilobytes, but in this
+ * Note: most libvirt APIs provide memory sizes in kibibytes, but in this
  * function the returned value is in bytes. Divide by 1024 as necessary.
  *
  * Returns the available free memory in bytes or 0 in case of error
@@ -7605,11 +7606,11 @@ error:
  * @flags: bitwise-OR of virDomainBlockResizeFlags
  *
  * Resize a block device of domain while the domain is running.  If
- * @flags is 0, then @size is in kibibytes (blocks of 1024); since
- * 0.9.11, if @flags includes VIR_DOMAIN_BLOCK_RESIZE_BYTES, @size is
- * in bytes instead.  @size is taken directly as the new size.
- * Depending on the file format, the hypervisor may round up to the
- * next alignment boundary.
+ * @flags is 0, then @size is in kibibytes (blocks of 1024 bytes);
+ * since 0.9.11, if @flags includes VIR_DOMAIN_BLOCK_RESIZE_BYTES,
+ * @size is in bytes instead.  @size is taken directly as the new
+ * size.  Depending on the file format, the hypervisor may round up
+ * to the next alignment boundary.
  *
  * The @disk parameter is either an unambiguous source name of the
  * block device (the <source file='...'/> sub-element, such as