Re: [libvirt] [PATCH v2] bandwidth: Adjust documentation

Because I know it's easier to read without all the git +/-, here's what I have now in the QoS section on the formatnetwork (hopefully I've captured everything correctly):

The <bandwidth> element allows setting quality of service for a particular network (since 0.9.4). Setting bandwidth for a network is supported only for networks with a <forward> mode of route, nat, or no mode at all (i.e. an "isolated" network). Setting bandwidth is not supported for forward modes of bridge, passthrough, private, or hostdev. Attempts to do this will lead to a failure to define the network or to create a transient network. The <bandwidth> element can only be a subelement of a domain's <interface>, a subelement of a <network>, or a subelement of a <portgroup> in a <network>. As a subelement of a domain's <interface>, the bandwidth only applies to that one interface of the domain. As a subelement of a <network>, the bandwidth is a total aggregate bandwidth to/from all guest interfaces attached to that network, not to each guest interface individually. If a domain's <interface> has <bandwidth> element values higher than the aggregate for the entire network, then the aggregate bandwidth for the <network> takes precedence. This is because the two choke points are independent of each other where the domain's <interface> bandwidth control is applied on the interface's tap device, while the <network> bandwidth control is applied on the interface part of the bridge device created for that network. As a subelement of a <portgroup> in a <network>, if a domain's <interface> has a portgroup attribute in its <source> element and if the <interface> itself has no <bandwidth> element, then the <bandwidth> element of the portgroup will be applied individually to each guest interface defined to be a member of that portgroup. Any <bandwidth> element in the domain's <interface> definition will override the setting in the portgroup (since 1.0.1). Incoming and outgoing traffic can be shaped independently. The bandwidth element can have at most one inbound and at most one outbound child element. Leaving either of these children elements out results in no QoS applied for that traffic direction. So, when you want to shape only incoming traffic, use inbound only, and vice versa. Each of these elements have one mandatory attribute - average (or floor as described below). The attributes are as follows, where accepted values for each attribute is an integer number. average Specifies the desired average bit rate for the interface being shaped (in kilobytes/second). peak Optional attribute which specifies the maximum rate at which the bridge can send data (in kilobytes/second). Note the limitation of implementation: this attribute in the outbound element is ignored (as Linux ingress filters don't know it yet). burst Optional attribute which specifies the amount of kilobytes that can be transmitted in a single burst at peak speed. floor Optional attribute available only for the inbound element. This attribute guarantees minimal throughput for shaped interfaces. This, however, requires that all traffic goes through one point where QoS decisions can take place, hence why this attribute works only for virtual networks for now (that is <interface type='network'/> with a forward type of route, nat, or no forward at all). Moreover, the virtual network the interface is connected to is required to have at least inbound QoS set (average at least). If using the floor attribute users don't need to specify average. However, peak and burst attributes still require average. Currently, the Linux kernel doesn't allow ingress qdiscs to have any classes therefore floor can be applied only on inbound and not outbound. Attributes average, peak, and burst are available since 0.9.4, while the floor attribute is available since 1.0.1.