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

[Jiri Denemark]

On Tue, Jul 12, 2011 at 13:57:07 +0200, Michal Privoznik wrote:
> 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.

tc is an internal implementation which we shouldn't expose externally. Instead
of allowing units, we can just select one fixed unit and have plain numbers in
the attributes. Kilobytes (per second) seems like a good unit for me since
it's small enough that I doubt anyone would need less than that and we use
kilobytes in other places as well (memory size, e.g.).

> 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>
> +  ...
> +  <devices>
> +    <interface type='network'>
> +      <source network='default'/>
> +      <target dev='vnet0'/>
> +      <b><bandwidth>
> +        <inbound average='1mbit' peak='0.5mbps' burst='1m'/>
> +        <outbound average='128kbit' peak='256kbit' burst='256kbit'/>
> +      </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 decimal
> +    numbers, optionally followed by unit. See <code>man tc</code> for more
> +    details.
> +  </p>

We shouldn't mention tc in XML documentation. The semantics should be
documented in a self-contained way.

>      <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>
> +  ...
> +      <forward mode='nat' dev='eth0'/>
> +      <b><bandwidth>
> +        <inbound average='1mbit' peak='0.5mbps' burst='1m'/>
> +        <outbound average='128kbit' peak='256kbit' burst='256kbit'/>
> +      </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 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>
> +

The same applies here.

...
> 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
> @@ -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>
> +

Remove the <interleave> around attributes, since it doesn't make sense here,
attributes can always be set in any order. And make all values be just plain
numbers.

...
> 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

The bandwidth XML element is not very complicated but it still seems better if
we have a single rng file defining the element and make both domain.rng and
network.rng include that file. We do the same with storageencryption.rng.

Jirka