[PATCH qemu-server v3 3/3] cpu: add CPU binding

[Elias Huhsovitz <e.huhsovitz@proxmox.com>]

Add two new VM config options:
* cpu-binding-mode  none | manual | one-to-one | numa | numa-manual
* cpu-binding-cfg   mode-dependent syntax

When cpu-binding-mode is unset or "none", behavior is unchanged.
Otherwise, vCPU threads are pinned to host CPUs after QEMU has spawned
them, driven by the query-cpus-fast QMP response.

Five modes are supported:
* manual - explicit vCPU:hostCPU mapping, e.g. "0:0;1:1;2:2;3:3"
* one-to-one - each vCPU gets its own physical core from a user pool,
  SMT stripped, e.g. "0-3"
* numa - per-vNUMA-node set-to-set binding, sequential, e.g. "3;4"
* numa-manual - explicit vNUMA->host NUMA mapping, e.g. "0:2;1:3"

Two entry points are provided in PVE::QemuServer::CPUBinding:
* validate_binding() - called at VM start, before QEMU spawns. Rejects
invalid configs against the current topology.

* bind_vcpus() - called after QEMU is up. Encodes the QMP cpu
information as JSON and hands it to Rust together with the mode and cfg
string.

Signed-off-by: Elias Huhsovitz <e.huhsovitz@proxmox.com>
---
 src/PVE/QemuServer.pm            |  36 +++++++++
 src/PVE/QemuServer/CPUBinding.pm | 133 +++++++++++++++++++++++++++++++
 src/PVE/QemuServer/Makefile      |   1 +
 3 files changed, 170 insertions(+)
 create mode 100644 src/PVE/QemuServer/CPUBinding.pm

diff --git a/src/PVE/QemuServer.pm b/src/PVE/QemuServer.pm
index 1efeeb66..3ba266be 100644
--- a/src/PVE/QemuServer.pm
+++ b/src/PVE/QemuServer.pm
@@ -60,6 +60,7 @@ use PVE::QemuServer::Helpers
     qw(config_aware_timeout get_iscsi_initiator_name get_host_arch min_version kvm_user_version windows_version);
 use PVE::QemuServer::Cloudinit;
 use PVE::QemuServer::CGroup;
+use PVE::QemuServer::CPUBinding;
 use PVE::QemuServer::CPUConfig qw(
     print_cpu_device
     get_cpu_options
@@ -739,6 +740,18 @@ EODESCR
         optional => 1,
         default => 1,
     },
+    'cpu-binding-mode' => {
+        type => 'string',
+        format => $PVE::QemuServer::Bind::bind_mode_fmt,
+        description => "Set CPU binding mode for the guest",
+        optional => 1,
+    },
+    'cpu-binding-cfg' => {
+        type => 'string',
+        format => $PVE::QemuServer::Bind::bind_cfg_fmt,
+        description => "Configuration for CPU binding for the guest",
+        optional => 1,
+    },
 };
 
 my $cicustom_fmt = {
@@ -3218,6 +3231,15 @@ sub config_to_command {
         push @$cmd, '/usr/bin/taskset', '--cpu-list', '--all-tasks', $conf->{affinity};
     }
 
+    if ($conf->{'cpu-binding-mode'}) {
+        PVE::QemuServer::CPUBinding::validate_binding(
+            $conf->{'cpu-binding-mode'},
+            $conf->{'sockets'},
+            $conf->{'cores'},
+            $conf->{'cpu-binding-cfg'},
+        );
+    }
+
     push @$cmd, $kvm_binary;
 
     push @$cmd, '-id', $vmid;
@@ -5715,6 +5737,20 @@ sub vm_start_nolock {
     my $qemu_pkg_string = PVE::QemuServer::QMPHelpers::get_qemu_package_string($vmid);
     syslog("info", "VM $vmid started with PID $pid using $qemu_pkg_string.");
 
+    if ($conf->{'cpu-binding-mode'}) {
+        eval {
+            PVE::QemuServer::CPUBinding::bind_vcpus(
+                $vmid,
+                $conf->{'cpu-binding-mode'},
+                $conf->{'cpu-binding-cfg'},
+            );
+            1;
+        } or do {
+            my $error = $@ || 'Unknown failure';
+            log_warn("unable to bind vCPU threads - $error");
+        };
+    }
+
     PVE::QemuServer::RunState::create_cleanup_flag($vmid);
 
     if (defined(my $migrate = $res->{migrate})) {
diff --git a/src/PVE/QemuServer/CPUBinding.pm b/src/PVE/QemuServer/CPUBinding.pm
new file mode 100644
index 00000000..3ce3653b
--- /dev/null
+++ b/src/PVE/QemuServer/CPUBinding.pm
@@ -0,0 +1,133 @@
+package PVE::QemuServer::CPUBinding;
+
+use v5.36;
+
+use JSON;
+
+use PVE::QemuServer::Monitor;
+use PVE::RS::CPU::Bind;
+
+our $bind_mode_fmt = {
+    mode => {
+        type => 'string',
+        enum => [qw(none manual one-to-one numa numa-manual)],
+        description => "Set the CPU binding mode for the guest.",
+        verbose_description => <<'EODESCR',
+Selects how guest vCPUs are pinned to host CPUs. The mode determines
+how cpu-binding-cfg is interpreted.
+
+* none (default): no binding.
+
+* manual: explicit vCPU-to-hostCPU mapping. The config string is a
+  semicolon-separated list of `<vcpu-set>:<hostcpu-set>` entries.
+  Example: `0:0;1:1;2:2;3:3` pins vCPU 0 to CPU 0, vCPU 1 to CPU 1,
+  etc. Multi-value sets use `a-b` ranges or `{a,b,c}` unions.
+
+* one-to-one: pin each vCPU to its own physical core, chosen from a
+  user-supplied pool. The config string is an upper bound: the list of
+  host cores the vCPUs may be assigned to. SMT siblings are stripped
+  from that pool before assignment, so each vCPU gets its own distinct
+  physical core, not a hyperthread.
+
+  If the pool has N cores and the VM has M vCPUs, each vCPU is pinned
+  to exactly one of the N cores (N must be >= M, otherwise validation
+  fails). For example, with `0-3` on a 4-vCPU VM, vCPU 0 gets core 0,
+  vCPU 1 gets core 1, and so on. Each vCPU is fixed to a single core,
+  it does not float within the pool. With `0;1;4;5` on the same VM,
+  vCPU 2 is pinned to core 4 and vCPU 3 to core 5, skipping cores 2-3.
+
+  An empty string means "use all physical cores on the host" as the
+  upper bound. On a host with 16 cores, that pins an N-vCPU VM to
+  cores 0, 1, ..., N-1 — one core per vCPU, SMT stripped.
+
+  Unlike `manual`, you do not specify which core each vCPU gets; that
+  assignment is up to hwloc. Use `manual` if you need a specific
+  vCPU-to-core mapping.
+
+* numa: bind the set of vCPUs of each guest vNUMA node to the set of
+  CPUs of a host NUMA node. The config string is a `;`-separated list
+  of host NUMA node indices, consumed in order: guest vNUMA 0 gets the
+  first host node, guest vNUMA 1 the second, and so on.
+
+  Each guest vNUMA node's vCPUs form a group that may run on any CPU
+  of the assigned host NUMA node — including its cores and SMT threads.
+  The host scheduler is free to migrate vCPUs within the node, but not
+  outside it. This is the intended trade-off: memory allocated by a
+  vCPU stays local to the host node it runs on (preserving NUMA
+  memory locality), while the scheduler still has room to balance
+  load across the node's cores and hyperthreads.
+
+  This is a set-to-set binding, not a per-vCPU assignment. All vCPUs
+  of a guest vNUMA node share the same host CPU pool. If you need
+  each vCPU pinned to its own distinct core, use one-to-one or manual
+  instead.
+
+  Example: `3;4` lets all vCPUs on guest vNUMA 0 run on any CPU of
+  host NUMA node 3, and all vCPUs on guest vNUMA 1 run on any CPU of
+  host NUMA node 4.
+
+  An empty string uses host NUMA nodes in ascending index order:
+  guest vNUMA 0 → host node 0, guest vNUMA 1 → host node 1, etc.
+
+* numa-manual: explicit variant of numa. The config string is a
+  `;`-separated list of `<guest-vnuma>:<host-numa>` pairs. Each guest
+  vNUMA node's set of vCPUs is bound to the set of CPUs of the
+  specified host NUMA node.
+
+  Semantics are identical to numa — vCPUs of a guest vNUMA node may
+  be scheduled on any CPU of the assigned host node, but cannot leave
+  it. Only the node mapping is explicit here.
+
+  Example: `0:2;1:3` binds all vCPUs on guest vNUMA 0 to host NUMA
+  node 2's CPUs, and all vCPUs on guest vNUMA 1 to host NUMA node 3's
+  CPUs.
+EODESCR
+        default => 'none',
+        default_key => 1,
+    },
+};
+
+our $bind_cfg_fmt = {
+    cfg => {
+        type => 'string',
+        description => "CPU binding configuration (syntax depends on cpu-binding-mode).",
+        verbose_description => <<'EODESCR',
+The exact syntax depends on cpu-binding-mode:
+
+* manual, one-to-one:
+    `;`-separated list of `<vcpu-set>:<hostcpu-set>` entries (manual)
+    or a plain host CPU list (one-to-one). CPU sets accept `a-b` ranges
+    and `{a,b,c}` unions.
+
+* numa:
+    `;`-separated list of host NUMA node indices, e.g. `3;4`.
+
+* numa-manual:
+    `;`-separated list of `<guest-vnuma>:<host-numa>` pairs, e.g. `0:2;1:3`.
+
+Host CPU and NUMA node indices are OS indices as reported by `lstopo -p`.
+EODESCR
+        default => '',
+        default_key => 1,
+    },
+};
+
+sub validate_binding($mode, $sockets, $cores, $binding_cfg) {
+    return if $mode eq 'none';
+
+    $binding_cfg //= '';
+
+    PVE::RS::CPU::Bind::validate_binding($mode, $sockets, $cores, $binding_cfg);
+}
+
+sub bind_vcpus($vmid, $mode, $binding_cfg) {
+    return if $mode eq 'none';
+
+    $binding_cfg //= '';
+
+    my $cpuinfo = PVE::QemuServer::Monitor::mon_cmd($vmid, 'query-cpus-fast');
+    my $cpuinfo_json = JSON::encode_json($cpuinfo);
+    PVE::RS::CPU::Bind::bind_vcpus($mode, $binding_cfg, $cpuinfo_json);
+}
+
+1;
diff --git a/src/PVE/QemuServer/Makefile b/src/PVE/QemuServer/Makefile
index 61ed1a4e..ee123cf5 100644
--- a/src/PVE/QemuServer/Makefile
+++ b/src/PVE/QemuServer/Makefile
@@ -8,6 +8,7 @@ SOURCES=Agent.pm	\
 	Cfg2Cmd.pm	\
 	CGroup.pm	\
 	Cloudinit.pm	\
+	CPUBinding.pm	\
 	CPUConfig.pm	\
 	CPUFlags.pm	\
 	DBusVMState.pm	\
-- 
2.47.3