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='1000' peak='2000' burst='5120'/>
  <outbound average='500'/>
</bandwidth>

Leaving any element out means not to shape traffic in that
direction.
The units for average and peak (rate) are in kilobytes per second,
for burst (size) are just in kilobytes.
This element can be inserted into domain's 'interface' and
'network'.

diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
index 83146ed7cfbd3cb2a369c8b631828019dea664ac..f40afc4ac93292ac94e7118f56f7ace31e9ef26c 100644 (file)
--- a/docs/formatdomain.html.in
+++ b/docs/formatdomain.html.in
@@ -1882,6 +1882,40 @@ 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='1000' peak='5000' burst='1024'/&gt;
+        &lt;outbound average='128' peak='256' burst='256'/&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 integer
+      numbers. The units for <code>average</code> and <code>peak</code> attributes
+      are kilobytes per second, and for the <code>burst</code> just kilobytes.
+      <span class="since">Since 0.9.4</span>
+    </p>
+
     <h4><a name="elementsInput">Input devices</a></h4>
 
     <p>

diff --git a/docs/formatnetwork.html.in b/docs/formatnetwork.html.in
index f9421c3f84ea5ac18845d85e9f17d330d69f6d53..f0ff703269a8481fbe358762fc663d3f77fa013e 100644 (file)
--- a/docs/formatnetwork.html.in
+++ b/docs/formatnetwork.html.in
@@ -101,6 +101,36 @@
         to this host. <span class="since">Since 0.3.0; 'mode' attribute since
         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='1000' peak='5000' burst='5120'/&gt;
+    &lt;outbound average='128' peak='256' burst='256'/&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 integer
+        numbers, The units for <code>average</code> and <code>peak</code> attributes
+        are kilobytes per second, and for the <code>burst</code> just kilobytes.
+        The rate is shared equally within domains connected to the network.
+        <span class="since">Since 0.9.4</span>
+      </p>
 
     <h3><a name="elementsAddress">Addressing</a></h3>
 

diff --git a/docs/schemas/domain.rng b/docs/schemas/domain.rng
index 43326ab05af591874eddf6051515a223847df89e..aa4ce69419cb7b004c698e6d0b6502a3704aee77 100644 (file)
--- a/docs/schemas/domain.rng
+++ b/docs/schemas/domain.rng
@@ -1189,6 +1189,9 @@
       <optional>
         <ref name="deviceBoot"/>
       </optional>
+      <optional>
+        <ref name="bandwidth"/>
+      </optional>
     </interleave>
   </define>
   <!--

diff --git a/docs/schemas/network.rng b/docs/schemas/network.rng
index 1adb553cebacded73dde38ebd1ca885bc0db3c35..1c44471271e1bafa75f3c848c5aefe07630ee86d 100644 (file)
--- a/docs/schemas/network.rng
+++ b/docs/schemas/network.rng
@@ -147,6 +147,9 @@
               </zeroOrMore>
             </element>
         </optional>
+       <optional>
+         <ref name="bandwidth"/>
+       </optional>
 
         <!-- <ip> element -->
         <zeroOrMore>

diff --git a/docs/schemas/networkcommon.rng b/docs/schemas/networkcommon.rng
index 025181387fecedc3c0fd2f74482378bc7cbad83c..3a168c337c24c8d8867e7c4fc0a929cf1e6c81b8 100644 (file)
--- a/docs/schemas/networkcommon.rng
+++ b/docs/schemas/networkcommon.rng
@@ -47,4 +47,52 @@
       </group>
     </choice>
   </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">
+    <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>
+  </define>
+
+  <define name="speed">
+    <data type="unsignedInt">
+      <param name="pattern">[0-9]+</param>
+      <param name="minInclusive">1</param>
+    </data>
+  </define>
+  <define name="BurstSize">
+    <data type="unsignedInt">
+      <param name="pattern">[0-9]+</param>
+      <param name="minInclusive">1</param>
+    </data>
+  </define>
 </grammar>