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

Wed Jul 20 21:56:33 UTC 2011

On 07/18/2011 04:05 PM, 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  |   33 +++++++++++++++++++++++++++
>   docs/formatnetwork.html.in |   30 +++++++++++++++++++++++++
>   docs/schemas/bandwidth.rng |   52 ++++++++++++++++++++++++++++++++++++++++++++
>   docs/schemas/domain.rng    |    4 +++
>   docs/schemas/network.rng   |    4 +++
>   5 files changed, 123 insertions(+), 0 deletions(-)
>   create mode 100644 docs/schemas/bandwidth.rng
>
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index a54ee6a..1fbca9d 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -1825,6 +1825,39 @@ 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..67dbc5b 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>
> +  ...
> +<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>
>
>       <p>
> diff --git a/docs/schemas/bandwidth.rng b/docs/schemas/bandwidth.rng
> new file mode 100644
> index 0000000..6719bcc
> --- /dev/null
> +++ b/docs/schemas/bandwidth.rng
> @@ -0,0 +1,52 @@
> +<!-- A Relax NG schema for the domain and network bandwidth XML format -->
> +<grammar xmlns="http://relaxng.org/ns/structure/1.0"
> +    datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
> +
> +<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>
> diff --git a/docs/schemas/domain.rng b/docs/schemas/domain.rng
> index 8a4e3fe..a43a937 100644
> --- a/docs/schemas/domain.rng
> +++ b/docs/schemas/domain.rng
> @@ -7,6 +7,7 @@
>
>     <include href='basictypes.rng'/>
>     <include href='storageencryption.rng'/>
> +<include href='bandwidth.rng'/>

I put several network-related rng definitions that I use in both 
domain.rng and network.rng (for the virtual switch patches) into a file 
called networkcommon.rng.Maybe you should put the bandwidth rng 
definitions there as well (assuming my patches get pushed).

Othewise, if you keep your own separate file you'll need to add that 
file in the following places in order for "make rpm" to succeed:

docs/schemas/Makefile.am
libvirt.spec.in
mingw32-libvirt.spec.in

(Since there's at least one other place I'd like to see the QoS 
integrated with my patches, I think it would be best to assume their 
existence, and use networkcommon.rng).

>
>     <!--
>       description element, maybe placed anywhere under the root
> @@ -1170,6 +1171,9 @@
>         <optional>
>           <ref name="deviceBoot"/>
>         </optional>
> +<optional>
> +<ref name="bandwidth"/>
> +</optional>
>       </interleave>
>     </define>
>     <define name="virtualPortProfile">
> diff --git a/docs/schemas/network.rng b/docs/schemas/network.rng
> index 6d9f06b..2456ed1 100644
> --- a/docs/schemas/network.rng
> +++ b/docs/schemas/network.rng
> @@ -7,6 +7,7 @@
>     </start>
>
>     <include href='basictypes.rng'/>
> +<include href='bandwidth.rng' />
>
>     <define name="network">
>
> @@ -110,6 +111,9 @@
>                 </zeroOrMore>
>               </element>
>           </optional>
> +<optional>
> +<ref name="bandwidth"/>
> +</optional>
>
>           <!--<ip>  element -->
>           <zeroOrMore>