[libvirt] [PATCH v2 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 | 50 ++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 162 insertions(+), 0 deletions(-) diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in index 269fc30..766b2bc 100644 --- a/docs/formatdomain.html.in +++ b/docs/formatdomain.html.in @@ -1825,6 +1825,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 f9421c3..607e1aa 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 8a4e3fe..e12f5b7 100644 --- a/docs/schemas/domain.rng +++ b/docs/schemas/domain.rng @@ -1170,6 +1170,9 @@ <optional> <ref name="deviceBoot"/> </optional> + <optional> + <ref name="bandwidth"/> + </optional> </interleave> </define> <define name="virtualPortProfile"> @@ -2349,6 +2352,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 @@ -2520,4 +2560,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 6d9f06b..8e86b05 100644 --- a/docs/schemas/network.rng +++ b/docs/schemas/network.rng @@ -110,6 +110,9 @@ </zeroOrMore> </element> </optional> + <optional> + <ref name="bandwidth"/> + </optional> <!-- <ip> element --> <zeroOrMore> @@ -172,4 +175,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