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

[Laine Stump]

On 07/22/2011 10:07 AM, Michal Privoznik wrote:
> 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'.
> ---
>   docs/formatdomain.html.in      |   34 ++++++++++++++++++++++++++++
>   docs/formatnetwork.html.in     |   30 +++++++++++++++++++++++++
>   docs/schemas/domain.rng        |    3 ++
>   docs/schemas/network.rng       |    3 ++
>   docs/schemas/networkcommon.rng |   48 ++++++++++++++++++++++++++++++++++++++++
>   5 files changed, 118 insertions(+), 0 deletions(-)
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 83146ed..f40afc4 100644
> --- 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>
> +  ...
> +<devices>
> +<interface type='network'>
> +<source network='default'/>
> +<target dev='vnet0'/>
> +<b><bandwidth>
> +<inbound average='1000' peak='5000' burst='1024'/>
> +<outbound average='128' peak='256' burst='256'/>
> +</bandwidth></b>
> +</interface>
> +<devices>
> +  ...</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 f9421c3..f0ff703 100644
> --- 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>
> +...
> +<forward mode='nat' dev='eth0'/>
> +<b><bandwidth>
> +<inbound average='1000' peak='5000' burst='5120'/>
> +<outbound average='128' peak='256' burst='256'/>
> +</bandwidth></b>
> +<mac address='00:16:3E:5D:C7:9E'/>
> +...</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 43326ab..aa4ce69 100644
> --- 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 1adb553..1c44471 100644
> --- 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 0251813..3a168c3 100644
> --- 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>

ACK.