From: Chun Feng Wu <wucf@linux.ibm.com>

* Refactor "diskIoTune" to extract common schema "iotune"
* Add new elements '<throttlegroups>'
* <ThrottleGroups> contains <ThrottleGroup> defintion, which references
  "iotune"

Signed-off-by: Chun Feng Wu <wucf@linux.ibm.com>
---
 docs/formatdomain.rst             |  26 +++
 src/conf/schemas/domaincommon.rng | 274 ++++++++++++++++--------------
 2 files changed, 174 insertions(+), 126 deletions(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 00f861e385..b7e1f9cc83 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -1957,6 +1957,32 @@ advertisements to the guest OS. (NB: Only qemu driver support)
    the guest OS itself can choose to circumvent the unavailability of the sleep
    states (e.g. S4 by turning off completely).
 
+Disk Throttle Group Management
+------------------------------
+
+:since:`Since 10.5.0` it is possible to create multiple named throttle groups
+and then reference them within ``throttlefilters`` to form filter chain in QEMU for
+specific disk. The limits(throttlegroups) are shared within domain, hence the same group
+can be referenced by different filters.
+
+::
+
+   <domain>
+     ...
+     <throttlegroups>
+       <throttlegroup>
+         <group_name>limit0</group_name>
+         <total_bytes_sec>10000000</total_bytes_sec>
+         <read_iops_sec>400000</read_iops_sec>
+         <write_iops_sec>100000</write_iops_sec>
+       </throttlegroup>
+     </throttlegroups>
+     ...
+   </domain>
+
+``throttlegroup``
+   It has the same sub-elements as ``iotune`` (See `Hard drives, floppy disks, CDROMs`_),
+   The difference is that <group_name> is required.
 
 Hypervisor features
 -------------------
diff --git a/src/conf/schemas/domaincommon.rng b/src/conf/schemas/domaincommon.rng
index a46a824f88..08c520e222 100644
--- a/src/conf/schemas/domaincommon.rng
+++ b/src/conf/schemas/domaincommon.rng
@@ -51,6 +51,7 @@
       </zeroOrMore>
       <ref name="os"/>
       <ref name="clock"/>
+      <ref name="throttlegroups"/>
       <ref name="resources"/>
       <ref name="features"/>
       <ref name="events"/>
@@ -6653,6 +6654,23 @@
       </interleave>
     </element>
   </define>
+  <define name="throttlegroup">
+    <element name="throttlegroup">
+      <ref name="iotune"/>
+    </element>
+  </define>
+  <!--
+      A set of optional throttlegroups
+    -->
+  <define name="throttlegroups">
+    <optional>
+      <element name="throttlegroups">
+        <zeroOrMore>
+          <ref name="throttlegroup"/>
+        </zeroOrMore>
+      </element>
+    </optional>
+  </define>
   <!--
       A set of optional features: PAE, APIC, ACPI, GIC, TCG,
       HyperV Enlightenment, KVM features, paravirtual spinlocks and HAP support
@@ -7615,134 +7633,138 @@
     </element>
   </define>
 
+  <define name="iotune">
+    <interleave>
+      <choice>
+        <element name="total_bytes_sec">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_bytes_sec">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_bytes_sec">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+      <choice>
+        <element name="total_iops_sec">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_iops_sec">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_iops_sec">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+      <choice>
+        <element name="total_bytes_sec_max">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_bytes_sec_max">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_bytes_sec_max">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+      <choice>
+        <element name="total_iops_sec_max">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_iops_sec_max">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_iops_sec_max">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+      <optional>
+        <element name="size_iops_sec">
+          <data type="unsignedLong"/>
+        </element>
+      </optional>
+      <optional>
+        <element name="group_name">
+          <text/>
+        </element>
+      </optional>
+      <choice>
+        <element name="total_bytes_sec_max_length">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_bytes_sec_max_length">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_bytes_sec_max_length">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+      <choice>
+        <element name="total_iops_sec_max_length">
+          <data type="unsignedLong"/>
+        </element>
+        <group>
+          <interleave>
+            <optional>
+              <element name="read_iops_sec_max_length">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+            <optional>
+              <element name="write_iops_sec_max_length">
+                <data type="unsignedLong"/>
+              </element>
+            </optional>
+          </interleave>
+        </group>
+      </choice>
+    </interleave>
+  </define>
+
   <define name="diskIoTune">
     <element name="iotune">
-      <interleave>
-        <choice>
-          <element name="total_bytes_sec">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_bytes_sec">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_bytes_sec">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-        <choice>
-          <element name="total_iops_sec">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_iops_sec">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_iops_sec">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-        <choice>
-          <element name="total_bytes_sec_max">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_bytes_sec_max">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_bytes_sec_max">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-        <choice>
-          <element name="total_iops_sec_max">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_iops_sec_max">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_iops_sec_max">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-        <optional>
-          <element name="size_iops_sec">
-            <data type="unsignedLong"/>
-          </element>
-        </optional>
-        <optional>
-          <element name="group_name">
-            <text/>
-          </element>
-        </optional>
-        <choice>
-          <element name="total_bytes_sec_max_length">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_bytes_sec_max_length">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_bytes_sec_max_length">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-        <choice>
-          <element name="total_iops_sec_max_length">
-            <data type="unsignedLong"/>
-          </element>
-          <group>
-            <interleave>
-              <optional>
-                <element name="read_iops_sec_max_length">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-              <optional>
-                <element name="write_iops_sec_max_length">
-                  <data type="unsignedLong"/>
-                </element>
-              </optional>
-            </interleave>
-          </group>
-        </choice>
-      </interleave>
+      <ref name="iotune"/>
     </element>
   </define>
 
-- 
2.34.1

On Wed, Jun 12, 2024 at 03:02:09 -0700, wucf@linux.ibm.com wrote:
> From: Chun Feng Wu <wucf@linux.ibm.com>

We tend to add also a justification/description of the change rather
than just mechanically outline what you did:

 Introduce schema for defining '<throttlegroups>' element which
 configures throttling groups which can be configured for multiple
 disks.

Or something similar.

> * Refactor "diskIoTune" to extract common schema "iotune"
> * Add new elements '<throttlegroups>'
> * <ThrottleGroups> contains <ThrottleGroup> defintion, which references
>   "iotune"
> 
> Signed-off-by: Chun Feng Wu <wucf@linux.ibm.com>
> ---
>  docs/formatdomain.rst             |  26 +++
>  src/conf/schemas/domaincommon.rng | 274 ++++++++++++++++--------------
>  2 files changed, 174 insertions(+), 126 deletions(-)
> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 00f861e385..b7e1f9cc83 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -1957,6 +1957,32 @@ advertisements to the guest OS. (NB: Only qemu driver support)
>     the guest OS itself can choose to circumvent the unavailability of the sleep
>     states (e.g. S4 by turning off completely).
>  
> +Disk Throttle Group Management
> +------------------------------
> +
> +:since:`Since 10.5.0` it is possible to create multiple named throttle groups

Don't forget to update to '10.7.0'

> +and then reference them within ``throttlefilters`` to form filter chain in QEMU for

... within ``throttlefilters`` sub-element of ``disk`` element ...

> +specific disk. The limits(throttlegroups) are shared within domain, hence the same group
> +can be referenced by different filters.

Reviewed-by: Peter Krempa <pkrempa@redhat.com>