[PATCH qemu-server 0/2] memory: add verbose_description to numa policy

[PATCH qemu-server 0/2] memory: add verbose_description to numa policy

[Maximiliano Sandoval]

Adds a more flavorful description to the NUMA policy option based on
both qemu and the kernel's documentation. For now we simply paste the
contents of the `qemu-system-x86_64(1)` manual.

One open question is if there is any precedent for URIs in verbose
descriptions.

This came up in a couple of cases in enterprise support where more
information was requested regarding the policy.

Regarding the 'default' value. NUMA policies were added on our side at
2ed5d5724 but there is no mention of why the 'default' policy is not
used as a default. On QEMU's side the first appearance of policies was a
2.1.0 (Aug 2014) and there was a 'default' value at that stage.

Maximiliano Sandoval (2):
  memory: add verbose_description to numa policy
  memory: add default numa allocation policy

 src/PVE/QemuServer/Memory.pm | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

-- 
2.47.3

[PATCH qemu-server 1/2] memory: add verbose_description to numa policy

[Maximiliano Sandoval]

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 src/PVE/QemuServer/Memory.pm | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
index 7ebfc545..bcf6f9c5 100644
--- a/src/PVE/QemuServer/Memory.pm
+++ b/src/PVE/QemuServer/Memory.pm
@@ -42,6 +42,16 @@ my $numa_fmt = {
         type => 'string',
         enum => [qw(preferred bind interleave)],
         description => "NUMA allocation policy.",
+        verbose_description => <<EODESC,
+NUMA allocation policy. Possible values are:
+
+ - preferred: prefer the given host node list for allocation
+ - bind: restrict memory allocation to the given host node list
+ - interleave: interleave memory allocations across the given host node list
+
+The models are explained in more details at the kernel's documentation
+https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
+EODESC
         optional => 1,
     },
 };
-- 
2.47.3

[PATCH qemu-server 2/2] memory: add default numa allocation policy

[Maximiliano Sandoval]

This follows the host numa policy.

Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
---
 src/PVE/QemuServer/Memory.pm | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
index bcf6f9c5..9e65b2b0 100644
--- a/src/PVE/QemuServer/Memory.pm
+++ b/src/PVE/QemuServer/Memory.pm
@@ -40,11 +40,12 @@ my $numa_fmt = {
     },
     policy => {
         type => 'string',
-        enum => [qw(preferred bind interleave)],
+        enum => [qw(default preferred bind interleave)],
         description => "NUMA allocation policy.",
         verbose_description => <<EODESC,
 NUMA allocation policy. Possible values are:
 
+ - default: default host policy
  - preferred: prefer the given host node list for allocation
  - bind: restrict memory allocation to the given host node list
  - interleave: interleave memory allocations across the given host node list
@@ -53,6 +54,7 @@ The models are explained in more details at the kernel's documentation
 https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
 EODESC
         optional => 1,
+        default => 'default',
     },
 };
 PVE::JSONSchema::register_format('pve-qm-numanode', $numa_fmt);
@@ -450,8 +452,7 @@ sub config {
                 my $hostnodes = print_numa_hostnodes($hostnodelists);
 
                 # policy
-                my $policy = $numa->{policy};
-                die "you need to define a policy for hostnode $hostnodes\n" if !$policy;
+                my $policy = $numa->{policy} // 'default';
                 $mem_object .= ",host-nodes=$hostnodes,policy=$policy";
             } else {
                 die "numa hostnodes need to be defined to use hugepages" if $conf->{hugepages};
-- 
2.47.3

Re: [PATCH qemu-server 2/2] memory: add default numa allocation policy

[Dominik Csapak]

just for clarity: was this requested or did you just notice that it was 
missing?

On 3/12/26 11:50 AM, Maximiliano Sandoval wrote:
> This follows the host numa policy.
> 
> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
> ---
>   src/PVE/QemuServer/Memory.pm | 7 ++++---
>   1 file changed, 4 insertions(+), 3 deletions(-)
> 
> diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
> index bcf6f9c5..9e65b2b0 100644
> --- a/src/PVE/QemuServer/Memory.pm
> +++ b/src/PVE/QemuServer/Memory.pm
> @@ -40,11 +40,12 @@ my $numa_fmt = {
>       },
>       policy => {
>           type => 'string',
> -        enum => [qw(preferred bind interleave)],
> +        enum => [qw(default preferred bind interleave)],
>           description => "NUMA allocation policy.",
>           verbose_description => <<EODESC,
>   NUMA allocation policy. Possible values are:
>   
> + - default: default host policy
>    - preferred: prefer the given host node list for allocation
>    - bind: restrict memory allocation to the given host node list
>    - interleave: interleave memory allocations across the given host node list
> @@ -53,6 +54,7 @@ The models are explained in more details at the kernel's documentation
>   https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
>   EODESC
>           optional => 1,
> +        default => 'default',
>       },
>   };
>   PVE::JSONSchema::register_format('pve-qm-numanode', $numa_fmt);
> @@ -450,8 +452,7 @@ sub config {
>                   my $hostnodes = print_numa_hostnodes($hostnodelists);
>   
>                   # policy
> -                my $policy = $numa->{policy};
> -                die "you need to define a policy for hostnode $hostnodes\n" if !$policy;
> +                my $policy = $numa->{policy} // 'default';

while the property itself was already optional (since it was only 
required when the hostnodes were given) when we add this
we should mark 'default' as the default in the schema.

otherwise we could keep this check here and not set a default.

>                   $mem_object .= ",host-nodes=$hostnodes,policy=$policy";
>               } else {
>                   die "numa hostnodes need to be defined to use hugepages" if $conf->{hugepages};

Re: [PATCH qemu-server 2/2] memory: add default numa allocation policy

[Maximiliano Sandoval]

Dominik Csapak <d.csapak@proxmox.com> writes:

> just for clarity: was this requested or did you just notice that it was missing?

I noticed a while ago it was missing and never went around to fix it.
Clarification was also requested a couple of times in enterprise
support.

> On 3/12/26 11:50 AM, Maximiliano Sandoval wrote:
>> This follows the host numa policy.
>> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
>> ---
>>   src/PVE/QemuServer/Memory.pm | 7 ++++---
>>   1 file changed, 4 insertions(+), 3 deletions(-)
>> diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
>> index bcf6f9c5..9e65b2b0 100644
>> --- a/src/PVE/QemuServer/Memory.pm
>> +++ b/src/PVE/QemuServer/Memory.pm
>> @@ -40,11 +40,12 @@ my $numa_fmt = {
>>       },
>>       policy => {
>>           type => 'string',
>> -        enum => [qw(preferred bind interleave)],
>> +        enum => [qw(default preferred bind interleave)],
>>           description => "NUMA allocation policy.",
>>           verbose_description => <<EODESC,
>>   NUMA allocation policy. Possible values are:
>>   + - default: default host policy
>>    - preferred: prefer the given host node list for allocation
>>    - bind: restrict memory allocation to the given host node list
>>    - interleave: interleave memory allocations across the given host node list
>> @@ -53,6 +54,7 @@ The models are explained in more details at the kernel's documentation
>>   https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
>>   EODESC
>>           optional => 1,
>> +        default => 'default',
>>       },
>>   };
>>   PVE::JSONSchema::register_format('pve-qm-numanode', $numa_fmt);
>> @@ -450,8 +452,7 @@ sub config {
>>                   my $hostnodes = print_numa_hostnodes($hostnodelists);
>>                     # policy
>> -                my $policy = $numa->{policy};
>> -                die "you need to define a policy for hostnode $hostnodes\n" if !$policy;
>> +                my $policy = $numa->{policy} // 'default';
>
> while the property itself was already optional (since it was only required when
> the hostnodes were given) when we add this
> we should mark 'default' as the default in the schema.

This was set as a default a couple of lines above, is this what you
meant?

>
> otherwise we could keep this check here and not set a default.
>

I will send a v2 where instead of `// 'default'` one checks for the
default value in the schema.

>>                   $mem_object .= ",host-nodes=$hostnodes,policy=$policy";
>>               } else {
>>                   die "numa hostnodes need to be defined to use hugepages" if $conf->{hugepages};

-- 
Maximiliano

Re: [PATCH qemu-server 2/2] memory: add default numa allocation policy

[Dominik Csapak]

On 3/12/26 3:39 PM, Maximiliano Sandoval wrote:
> Dominik Csapak <d.csapak@proxmox.com> writes:
> 
>> just for clarity: was this requested or did you just notice that it was missing?
> 
> I noticed a while ago it was missing and never went around to fix it.
> Clarification was also requested a couple of times in enterprise
> support.

ok

> 
>> On 3/12/26 11:50 AM, Maximiliano Sandoval wrote:
>>> This follows the host numa policy.
>>> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
>>> ---
>>>    src/PVE/QemuServer/Memory.pm | 7 ++++---
>>>    1 file changed, 4 insertions(+), 3 deletions(-)
>>> diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
>>> index bcf6f9c5..9e65b2b0 100644
>>> --- a/src/PVE/QemuServer/Memory.pm
>>> +++ b/src/PVE/QemuServer/Memory.pm
>>> @@ -40,11 +40,12 @@ my $numa_fmt = {
>>>        },
>>>        policy => {
>>>            type => 'string',
>>> -        enum => [qw(preferred bind interleave)],
>>> +        enum => [qw(default preferred bind interleave)],
>>>            description => "NUMA allocation policy.",
>>>            verbose_description => <<EODESC,
>>>    NUMA allocation policy. Possible values are:
>>>    + - default: default host policy
>>>     - preferred: prefer the given host node list for allocation
>>>     - bind: restrict memory allocation to the given host node list
>>>     - interleave: interleave memory allocations across the given host node list
>>> @@ -53,6 +54,7 @@ The models are explained in more details at the kernel's documentation
>>>    https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
>>>    EODESC
>>>            optional => 1,
>>> +        default => 'default',
>>>        },
>>>    };
>>>    PVE::JSONSchema::register_format('pve-qm-numanode', $numa_fmt);
>>> @@ -450,8 +452,7 @@ sub config {
>>>                    my $hostnodes = print_numa_hostnodes($hostnodelists);
>>>                      # policy
>>> -                my $policy = $numa->{policy};
>>> -                die "you need to define a policy for hostnode $hostnodes\n" if !$policy;
>>> +                my $policy = $numa->{policy} // 'default';
>>
>> while the property itself was already optional (since it was only required when
>> the hostnodes were given) when we add this
>> we should mark 'default' as the default in the schema.
> 
> This was set as a default a couple of lines above, is this what you
> meant?

ahh oops, i did not see that, then disregard these comments here ;)

> 
>>
>> otherwise we could keep this check here and not set a default.
>>
> 
> I will send a v2 where instead of `// 'default'` one checks for the
> default value in the schema.

no IMO it's fine as it is, just wanted to give an alternative to setting
the default, but since you did that already that's not necessary.

> 
>>>                    $mem_object .= ",host-nodes=$hostnodes,policy=$policy";
>>>                } else {
>>>                    die "numa hostnodes need to be defined to use hugepages" if $conf->{hugepages};
> 

superseded: [PATCH qemu-server 2/2] memory: add default numa allocation policy

[Maximiliano Sandoval]

Dominik Csapak <d.csapak@proxmox.com> writes:

> On 3/12/26 3:39 PM, Maximiliano Sandoval wrote:
>> Dominik Csapak <d.csapak@proxmox.com> writes:
>> 
>>> just for clarity: was this requested or did you just notice that it was missing?
>> I noticed a while ago it was missing and never went around to fix it.
>> Clarification was also requested a couple of times in enterprise
>> support.
>
> ok
>
>> 
>>> On 3/12/26 11:50 AM, Maximiliano Sandoval wrote:
>>>> This follows the host numa policy.
>>>> Signed-off-by: Maximiliano Sandoval <m.sandoval@proxmox.com>
>>>> ---
>>>>    src/PVE/QemuServer/Memory.pm | 7 ++++---
>>>>    1 file changed, 4 insertions(+), 3 deletions(-)
>>>> diff --git a/src/PVE/QemuServer/Memory.pm b/src/PVE/QemuServer/Memory.pm
>>>> index bcf6f9c5..9e65b2b0 100644
>>>> --- a/src/PVE/QemuServer/Memory.pm
>>>> +++ b/src/PVE/QemuServer/Memory.pm
>>>> @@ -40,11 +40,12 @@ my $numa_fmt = {
>>>>        },
>>>>        policy => {
>>>>            type => 'string',
>>>> -        enum => [qw(preferred bind interleave)],
>>>> +        enum => [qw(default preferred bind interleave)],
>>>>            description => "NUMA allocation policy.",
>>>>            verbose_description => <<EODESC,
>>>>    NUMA allocation policy. Possible values are:
>>>>    + - default: default host policy
>>>>     - preferred: prefer the given host node list for allocation
>>>>     - bind: restrict memory allocation to the given host node list
>>>>     - interleave: interleave memory allocations across the given host node list
>>>> @@ -53,6 +54,7 @@ The models are explained in more details at the kernel's documentation
>>>>    https://docs.kernel.org/admin-guide/mm/numa_memory_policy.html#components-of-memory-policies.
>>>>    EODESC
>>>>            optional => 1,
>>>> +        default => 'default',
>>>>        },
>>>>    };
>>>>    PVE::JSONSchema::register_format('pve-qm-numanode', $numa_fmt);
>>>> @@ -450,8 +452,7 @@ sub config {
>>>>                    my $hostnodes = print_numa_hostnodes($hostnodelists);
>>>>                      # policy
>>>> -                my $policy = $numa->{policy};
>>>> -                die "you need to define a policy for hostnode $hostnodes\n" if !$policy;
>>>> +                my $policy = $numa->{policy} // 'default';
>>>
>>> while the property itself was already optional (since it was only required when
>>> the hostnodes were given) when we add this
>>> we should mark 'default' as the default in the schema.
>> This was set as a default a couple of lines above, is this what you
>> meant?
>
> ahh oops, i did not see that, then disregard these comments here ;)
>
>> 
>>>
>>> otherwise we could keep this check here and not set a default.
>>>
>> I will send a v2 where instead of `// 'default'` one checks for the
>> default value in the schema.
>
> no IMO it's fine as it is, just wanted to give an alternative to setting
> the default, but since you did that already that's not necessary.
>
>> 
>>>>                    $mem_object .= ",host-nodes=$hostnodes,policy=$policy";
>>>>                } else {
>>>>                    die "numa hostnodes need to be defined to use hugepages" if $conf->{hugepages};
>> 

Superseded-by: https://lore.proxmox.com/all/20260312145423.434537-1-m.sandoval@proxmox.com/T/#u
-- 
Maximiliano

Re: [PATCH qemu-server 0/2] memory: add verbose_description to numa policy

[Dominik Csapak]

both commit message could be longer (or be there at all ;) )
one could note e.g. that the description was taken
from the qemu manpage.

aside from that and the one comment on 2/2 (see separate mail) patches LGTM

On 3/12/26 11:50 AM, Maximiliano Sandoval wrote:
> Adds a more flavorful description to the NUMA policy option based on
> both qemu and the kernel's documentation. For now we simply paste the
> contents of the `qemu-system-x86_64(1)` manual.
> 
> One open question is if there is any precedent for URIs in verbose
> descriptions.
> 
> This came up in a couple of cases in enterprise support where more
> information was requested regarding the policy.
> 
> Regarding the 'default' value. NUMA policies were added on our side at
> 2ed5d5724 but there is no mention of why the 'default' policy is not
> used as a default. On QEMU's side the first appearance of policies was a
> 2.1.0 (Aug 2014) and there was a 'default' value at that stage.
> 
> Maximiliano Sandoval (2):
>    memory: add verbose_description to numa policy
>    memory: add default numa allocation policy
> 
>   src/PVE/QemuServer/Memory.pm | 17 ++++++++++++++---
>   1 file changed, 14 insertions(+), 3 deletions(-)
>