[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCH 1/7] bandwidth: Define schema and create documentation



Define new 'bandwidth' element with possible child element 'inbound'
and 'outbound' addressing incoming and outgoing traffic respectively:

<bandwidth>
  <inbound average='1mbit' peak='2mbit' burst='5m'/>
  <outbound average='0.5mbit'/>
</bandwidth>

Leaving any element out means not to shape traffic in that direction.
Accepted units are the same as 'tc' accepts.
This element can be inserted into domain's 'interface' and 'network'.
---
 docs/formatdomain.html.in  |   32 +++++++++++++++++++++++++++
 docs/formatnetwork.html.in |   30 +++++++++++++++++++++++++
 docs/schemas/domain.rng    |   50 +++++++++++++++++++++++++++++++++++++++++++
 docs/schemas/network.rng   |   51 ++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 163 insertions(+), 0 deletions(-)

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 39e1a85..3bd2440 100644
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1776,6 +1776,38 @@ qemu-kvm -net nic,model=? /dev/null
       <span class="since">Since 0.8.8</span>
     </p>
 
+    <h5><a name="elementQoS">Quality of service</a></h5>
+
+<pre>
+  ...
+  &lt;devices&gt;
+    &lt;interface type='network'&gt;
+      &lt;source network='default'/&gt;
+      &lt;target dev='vnet0'/&gt;
+      <b>&lt;bandwidth&gt;
+        &lt;inbound average='1mbit' peak='0.5mbps' burst='1m'/&gt;
+        &lt;outbound average='128kbit' peak='256kbit' burst='256kbit'/&gt;
+      &lt;/bandwidth&gt;</b>
+    &lt;/interface&gt;
+  &lt;devices&gt;
+  ...</pre>
+
+  <p>
+    This part of interface XML provides setting quality of service. Incoming
+    and outgoing traffic can be shaped independently. The
+    <code>bandwidth</code> element can have at most one <code>inbound</code>
+    and at most one <code>outbound</code> child elements. Leaving any of these
+    children element out result in no QoS applied on that traffic direction.
+    So, when you want to shape only domain's incoming traffic, use
+    <code>inbound</code> only, and vice versa. Each of these elements have one
+    mandatory attribute <code>average</code>. It specifies average bit rate on
+    interface being shaped. Then there are two optional attributes:
+    <code>peak</code>, which specifies maximum rate at which interface can send
+    data, and <code>burst</code>, amount of bytes that can be burst at
+    <code>peak</code> speed. Accepted values for attributes are decimal
+    numbers, optionally followed by unit. See <code>man tc</code> for more
+    details.
+  </p>
     <h4><a name="elementsInput">Input devices</a></h4>
 
     <p>
diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index 589aaff..d222704 100644
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -102,6 +102,36 @@
         0.4.2</span></dd>
     </dl>
 
+    <h5><a name="elementQoS">Quality of service</a></h5>
+
+<pre>
+  ...
+      &lt;forward mode='nat' dev='eth0'/&gt;
+      <b>&lt;bandwidth&gt;
+        &lt;inbound average='1mbit' peak='0.5mbps' burst='1m'/&gt;
+        &lt;outbound average='128kbit' peak='256kbit' burst='256kbit'/&gt;
+      &lt;/bandwidth&gt;</b>
+      &lt;mac address='00:16:3E:5D:C7:9E'/&gt;
+  ...</pre>
+
+  <p>
+    This part of network XML provides setting quality of service. Incoming
+    and outgoing traffic can be shaped independently. The
+    <code>bandwidth</code> element can have at most one <code>inbound</code>
+    and at most one <code>outbound</code> child elements. Leaving any of these
+    children element out result in no QoS applied on that traffic direction.
+    So, when you want to shape only network's incoming traffic, use
+    <code>inbound</code> only, and vice versa. Each of these elements have one
+    mandatory attribute <code>average</code>. It specifies average bit rate on
+    interface being shaped. Then there are two optional attributes:
+    <code>peak</code>, which specifies maximum rate at which bridge can send
+    data, and <code>burst</code>, amount of bytes that can be burst at
+    <code>peak</code> speed. Accepted values for attributes are decimal
+    numbers, optionally followed by unit. See <code>man tc</code> for
+    more details. The rate is shared equally within domains connected
+    to the network.
+  </p>
+
     <h3><a name="elementsAddress">Addressing</a></h3>
 
     <p>
diff --git a/docs/schemas/domain.rng b/docs/schemas/domain.rng
index 891662d..b15c8e5 100644
--- a/docs/schemas/domain.rng
+++ b/docs/schemas/domain.rng
@@ -1155,6 +1155,9 @@
       <optional>
         <ref name="deviceBoot"/>
       </optional>
+      <optional>
+        <ref name="bandwidth"/>
+      </optional>
     </interleave>
   </define>
   <define name="virtualPortProfile">
@@ -2307,6 +2310,43 @@
     </element>
   </define>
 
+  <define name="bandwidth">
+    <element name="bandwidth">
+      <interleave>
+        <optional>
+          <element name="inbound">
+            <ref name="bandwidth-attributes"/>
+            <empty/>
+          </element>
+        </optional>
+        <optional>
+          <element name="outbound">
+            <ref name="bandwidth-attributes"/>
+            <empty/>
+          </element>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="bandwidth-attributes">
+    <interleave>
+      <attribute name="average">
+        <ref name="speed"/>
+      </attribute>
+      <optional>
+        <attribute name="peak">
+          <ref name="speed"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name='burst'>
+          <ref name="BurstSize"/>
+        </attribute>
+      </optional>
+    </interleave>
+  </define>
+
   <!--
        Optional hypervisor extensions in their own namespace:
          QEmu
@@ -2557,4 +2597,14 @@
       <param name="maxLength">39</param>
     </data>
   </define>
+  <define name="speed">
+    <data type="string">
+      <param name="pattern">[0-9]+(\.[0-9]+)?((Ki|k|mi|m|gi|g|ti|t|)?bit|(Ki|K|Mi|M|Gi|G|Ti|T)?Bps)?</param>
+    </data>
+  </define>
+  <define name="BurstSize">
+    <data type="string">
+      <param name="pattern">[0-9]+(\.[0-9]+)?(kb|k|mb|m|mbit|kbit|b|gb|g|gbit)?</param>
+    </data>
+  </define>
 </grammar>
diff --git a/docs/schemas/network.rng b/docs/schemas/network.rng
index 6d01b06..b3b7bcf 100644
--- a/docs/schemas/network.rng
+++ b/docs/schemas/network.rng
@@ -87,6 +87,10 @@
           </element>
         </optional>
 
+        <optional>
+          <ref name="bandwidth"/>
+        </optional>
+
         <!-- <ip> element -->
         <zeroOrMore>
           <!-- The IP element sets up NAT'ing and an optional DHCP server
@@ -183,4 +187,51 @@
     </data>
   </define>
 
+  <define name="bandwidth">
+    <element name="bandwidth">
+      <interleave>
+        <optional>
+          <element name="inbound">
+            <ref name="bandwidth-attributes"/>
+            <empty/>
+          </element>
+        </optional>
+        <optional>
+          <element name="outbound">
+            <ref name="bandwidth-attributes"/>
+            <empty/>
+          </element>
+        </optional>
+      </interleave>
+    </element>
+  </define>
+
+  <define name="bandwidth-attributes">
+    <interleave>
+      <attribute name="average">
+        <ref name="speed"/>
+      </attribute>
+      <optional>
+        <attribute name="peak">
+          <ref name="speed"/>
+        </attribute>
+      </optional>
+      <optional>
+        <attribute name='burst'>
+          <ref name="BurstSize"/>
+        </attribute>
+      </optional>
+    </interleave>
+  </define>
+
+  <define name="speed">
+    <data type="string">
+      <param name="pattern">[0-9]+(\.[0-9]+)?((Ki|k|mi|m|gi|g|ti|t|)?bit|(Ki|K|Mi|M|Gi|G|Ti|T)?Bps)?</param>
+    </data>
+  </define>
+  <define name="BurstSize">
+    <data type="string">
+      <param name="pattern">[0-9]+(\.[0-9]+)?(kb|k|mb|m|mbit|kbit|b|gb|g|gbit)?</param>
+    </data>
+  </define>
 </grammar>
-- 
1.7.5.rc3


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]