Document the iothread poll-weight XML attribute in formatdomain.

Extend the description of iothread polling controls to cover the new
poll-weight attribute and how it relates to the existing poll-max,
poll-grow, and poll-shrink settings. Also document the accepted
range and the meaning of zero as a request for the hypervisor
default.

Signed-off-by: Jaehoon Kim <jhkim@linux.ibm.com>
---
 docs/formatdomain.rst | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 3ba981422f..b173fc897b 100644
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -815,7 +815,7 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
        <iothread id="4"/>
        <iothread id="6"/>
        <iothread id="8" thread_pool_min="2" thread_pool_max="32">
-         <poll max='123' grow='456' shrink='789'/>
+         <poll max='123' grow='456' shrink='789' weight='3'/>
        </iothread>
      </iothreadids>
      <defaultiothread thread_pool_min="8" thread_pool_max="16"/>
@@ -849,6 +849,12 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
    polling. Attributes ``grow`` and ``shrink`` override (or disable when set to
    ``0``) the default steps for increasing/decreasing the polling interval if
    the set interval is deemed insufficient or excessive.
+   :since:`Since 12.6.0` the optional attribute ``weight`` sets the shift value
+   for the adaptive polling algorithm, controlling how much the most recent
+   event interval affects the next polling duration calculation. Larger values
+   decrease the weight of recent events, producing more gradual adjustments.
+   Valid range is ``[0, 63]``. Setting ``weight`` to ``0`` lets the hypervisor
+   select its default value.
 ``defaultiothread``
    This element represents the default event loop within hypervisor, where I/O
    requests from devices not assigned to a specific IOThread are processed.
-- 
2.54.0

On Wed, Jul 22, 2026 at 13:52:15 -0500, Jaehoon Kim wrote:
> Document the iothread poll-weight XML attribute in formatdomain.
> 
> Extend the description of iothread polling controls to cover the new
> poll-weight attribute and how it relates to the existing poll-max,
> poll-grow, and poll-shrink settings. Also document the accepted
> range and the meaning of zero as a request for the hypervisor
> default.
> 
> Signed-off-by: Jaehoon Kim <jhkim@linux.ibm.com>
> ---
>  docs/formatdomain.rst | 8 +++++++-
>  1 file changed, 7 insertions(+), 1 deletion(-)

Please move this patch right after the patch which adds the XML
parser/formatter bits.

> 
> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
> index 3ba981422f..b173fc897b 100644
> --- a/docs/formatdomain.rst
> +++ b/docs/formatdomain.rst
> @@ -815,7 +815,7 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
>         <iothread id="4"/>
>         <iothread id="6"/>
>         <iothread id="8" thread_pool_min="2" thread_pool_max="32">
> -         <poll max='123' grow='456' shrink='789'/>
> +         <poll max='123' grow='456' shrink='789' weight='3'/>
>         </iothread>
>       </iothreadids>
>       <defaultiothread thread_pool_min="8" thread_pool_max="16"/>
> @@ -849,6 +849,12 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
>     polling. Attributes ``grow`` and ``shrink`` override (or disable when set to
>     ``0``) the default steps for increasing/decreasing the polling interval if
>     the set interval is deemed insufficient or excessive.
> +   :since:`Since 12.6.0` the optional attribute ``weight`` sets the shift value

12.7.0

> +   for the adaptive polling algorithm, controlling how much the most recent
> +   event interval affects the next polling duration calculation. Larger values
> +   decrease the weight of recent events, producing more gradual adjustments.
> +   Valid range is ``[0, 63]``. Setting ``weight`` to ``0`` lets the hypervisor
> +   select its default value.

Also omitting it is equivalent to 0. As said in the previous patch I'm
not sure if we shouldn't drop the 'weight' parameter in the XML if it's
parsed as 0 to have only 1 manifestation of the default.

>  ``defaultiothread``
>     This element represents the default event loop within hypervisor, where I/O
>     requests from devices not assigned to a specific IOThread are processed.
> -- 
> 2.54.0
>

On 7/29/2026 9:34 AM, Peter Krempa wrote:
> On Wed, Jul 22, 2026 at 13:52:15 -0500, Jaehoon Kim wrote:
>> Document the iothread poll-weight XML attribute in formatdomain.
>>
>> Extend the description of iothread polling controls to cover the new
>> poll-weight attribute and how it relates to the existing poll-max,
>> poll-grow, and poll-shrink settings. Also document the accepted
>> range and the meaning of zero as a request for the hypervisor
>> default.
>>
>> Signed-off-by: Jaehoon Kim <jhkim@linux.ibm.com>
>> ---
>>   docs/formatdomain.rst | 8 +++++++-
>>   1 file changed, 7 insertions(+), 1 deletion(-)
> Please move this patch right after the patch which adds the XML
> parser/formatter bits.

I'll move this patch right after the XML parser/formatter patch in v2.

>
>> diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
>> index 3ba981422f..b173fc897b 100644
>> --- a/docs/formatdomain.rst
>> +++ b/docs/formatdomain.rst
>> @@ -815,7 +815,7 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
>>          <iothread id="4"/>
>>          <iothread id="6"/>
>>          <iothread id="8" thread_pool_min="2" thread_pool_max="32">
>> -         <poll max='123' grow='456' shrink='789'/>
>> +         <poll max='123' grow='456' shrink='789' weight='3'/>
>>          </iothread>
>>        </iothreadids>
>>        <defaultiothread thread_pool_min="8" thread_pool_max="16"/>
>> @@ -849,6 +849,12 @@ host/guest with many LUNs. :since:`Since 1.2.8 (QEMU only)`
>>      polling. Attributes ``grow`` and ``shrink`` override (or disable when set to
>>      ``0``) the default steps for increasing/decreasing the polling interval if
>>      the set interval is deemed insufficient or excessive.
>> +   :since:`Since 12.6.0` the optional attribute ``weight`` sets the shift value
> 12.7.0

I'll fix it.

>
>> +   for the adaptive polling algorithm, controlling how much the most recent
>> +   event interval affects the next polling duration calculation. Larger values
>> +   decrease the weight of recent events, producing more gradual adjustments.
>> +   Valid range is ``[0, 63]``. Setting ``weight`` to ``0`` lets the hypervisor
>> +   select its default value.
> Also omitting it is equivalent to 0. As said in the previous patch I'm
> not sure if we shouldn't drop the 'weight' parameter in the XML if it's
> parsed as 0 to have only 1 manifestation of the default.

I agree that having two representations of the default value is not ideal.
However, I would prefer to keep accepting an explicit weight='0' value for
consistency with the existing grow and shrink attributes, which use the same
convention.

Also, keeping 0 as an explicit value leaves room for potential future use if
0 gains a different meaning,.

Therefore, I would prefer to preserve a explicit weight='0' away at this point.

Thanks,
Jaehoon

>>   ``defaultiothread``
>>      This element represents the default event loop within hypervisor, where I/O
>>      requests from devices not assigned to a specific IOThread are processed.
>> -- 
>> 2.54.0
>>