Repository navigation
Description
Helios has no notion of memory locality. No backend reads a NUMA description (ACPI SRAT and SLIT, or the device tree's numa-node-id and distance-map): the firmware tables parsed today are MADT and SPCR. hal hands the kernel memory as a flat list of regions (hal::memory::MemoryRegion) and processors as a table with no node. The frame allocator, the per-processor frame cache (kernel/src/memory/frame_slab.rs), the pooling allocator's linear-memory slots, fiber stacks and the executor's work stealing all treat every frame and every processor as equidistant.
On a single-node guest that is exact. On a multi-node one (a large cloud instance type, a multi-socket host) an instance's memory lands on whichever node the allocator reaches first and its task migrates across nodes freely, where Linux under the same Wasmtime allocates first-touch on the running processor's node and keeps a task near its memory. That is a parity loss (#311) on every memory-bound workload, and one no current lane can see: every lane boots a single-node guest.
Scope
- Contract (
hal). A memory region and a processor each carry a node, and the platform publishes the node distance matrix. A platform with no NUMA description is one node, with no special case in the kernel. - Backends. x86-64 and aarch64 read SRAT and SLIT; aarch64 and riscv64 read
numa-node-idanddistance-mapwhen booted from a device tree. - Memory. Frames are pooled per node. A processor's frame cache refills from its own node and falls back in distance order; a free returns a frame to the node it came from, whichever processor frees it. Linear-memory slots, fiber stacks and kernel per-processor structures are backed from the node of the processor they serve.
- Scheduling. Work stealing prefers a victim on the thief's node before a remote one, and an instance's home is the node its memory was committed on.
- Observation. The boot line reports the node count, each node's memory and processors, and
helios:system/statsreports per-node free memory and the count of off-node allocations.
Each new structure states which of its operations run on the owning processor and which arrive from any (§3.5).
Done when
- Each architecture boots a two-node guest (
-numa nodewith a memory backend per node) in its smoke lane and the boot line matches the topology QEMU published. - A kernel test drives allocation on a two-node memory plan and asserts node-local placement, distance-ordered fallback and that a cross-processor free returns the frame to its node.
- A single-node boot shows no regression on the paired lane.
- The performance claim is measured on a host with more than one physical node. An emulated topology on a single-node host has uniform memory latency, so it proves placement and nothing about speed.
Activity
lexoliu commentedon Nov 11, 2026
NUMA topology for Helios (#516): design
All file:line citations below are against
origin/devat6716675b. A citation into a third-party crate gives the crate version and a path inside its published source.0. Summary
halgains anumamodule with four parts: aNumaTopologytrait that every backend implements, a denseNodeId,NodeDistancein SLIT units, and aSingleNodeimplementation.MemoryRegionbecomes a struct that carries itsNodeId. The firmware readers live in a new#![no_std]library crate,firmware/(helios-firmware): ACPI SRAT/SLIT through theacpicrate for x86-64 and aarch64, and devicetreenuma-node-id/distance-mapthroughfdtfor aarch64 and riscv64.The kernel copies the description once, at
prime_bootstrap_allocator, into an immutableLocality. It then splits the user pool into one buddy pool per node and gives each processor's frame cache one list per node, following Linux's per-zoneper_cpu_pages. Allocation follows a distance-ordered memory order per node. Per-processor structures are carved from a node-local arena. The executor's single global ready queue becomes one queue per node, drained in distance order. An instance's home node is fixed at its first processor turn, which is where Wasmtime commits its linear memory.A machine with no NUMA description is
SingleNode: one pool, one queue per node, an empty remote order. No branch in the kernel distinguishes it.1. Consumer inventory
1.1 How memory reaches the allocator today
hal::memory::MemoryRegionisNonNull<[u8]>(hal/src/memory.rs:3).hal::memory::MemoryMap(hal/src/memory.rs:5-11) has no implementor and no consumer.git grep -w MemoryMapfinds only its definition and an unrelated generic parameter name in hal/src/boot.rs:98.helios_kernel::prime_bootstrap_allocator(regions, processor_count)(kernel/src/lib.rs:1275-1291). It is called by:init→bootstrap_init(kernel/src/lib.rs:1153, 1305).Platform::memory_regionsis dead on three backends.core::iter::empty()(aarch64/src/lib.rs:621).inittakes theBOOT_INITIALIZINGbranch and never reads them (kernel/src/lib.rs:1155).init_allocator(kernel/src/lib.rs:1203-1273):ArrayVec(MAX_BOOT_MEMORY_REGIONS, kernel/src/lib.rs:811);BootMemoryPlan;BootRegionSplitter, kernel/src/memory/policy.rs:246-283);UserMemoryPoolwith the rest (kernel/src/lib.rs:1271);processor_count(kernel/src/lib.rs:1249-1257).boot_memory_regions(x86/src/lib.rs:691-714) and aarch64boot_memory_regions(aarch64/src/lib.rs:2189-2207) are the same function. §1 requires the change that notices this to fix it.1.2 Consumers and what each needs from the topology
UserMemoryPool(kernel/src/memory/user.rs:20-32)IrqSafeMutex<FramePool>buddy, oneFrameSlabCache, oneReportedFramesbitmap, onetotal_bytes.FramePool::initialize(kernel/src/memory/frame_pool.rs:44-85)SummaryBuddyAllocatorover the span from the lowest to the highest region, with metadata inside that span.allocate_raw(user.rs:192-232)try_allocate_frame_on(user.rs:250-273), fault pathFrameSlabCache(kernel/src/memory/frame_slab.rs:32-40, 118-221)deallocate_on(processor)pushes into the freeing processor's shard (frame_slab.rs:155-162), whatever the frame's origin. Per-shard capacity istotal/64/(shards+1)(frame_slab.rs:200-206).deallocate_with_processor(user.rs:289-308)lend_to_kernel_heap(user.rs:75-85)largest_servable_bytes(user.rs:167-186)BootMemoryPlan/BootRegionSplitter(policy.rs:150-293)frame_reserve(kernel/src/memory/frame_reserve.rs:23-49, 270-315)UserMemoryOwners(kernel/src/memory/owner.rs:57-77)frame_reserve::take_frame(current_processor())at fault time (fiber_stack.rs:471-472, 531). Warm slots keep the pages of whoever last ran on them (fiber_stack.rs:18-32).take_slottakes the lowest slot in a state (fiber_stack.rs:557). Per-processordemand_commits/announcedarrays (fiber_stack.rs:228, 232).AddressSpace::commit(hal/src/vmm.rs:332) on the processor running the store's turn, viaallocate_user_frame_zeroed_on(current). Call sites: x86/src/vmm.rs:476-480; aarch64/src/vmm.rs:658; riscv/src/vmm.rs:580. Every backend ships the no-image hook (x86/src/vmm.rs:1329; aarch64/src/vmm.rs:1676; riscv/src/vmm.rs:1457), so data segments are copied into the instance's own pages.linear_memory_keep_resident: 0was read from a different Wasmtime branch than docs/wasmtime.md pins. What placement does need is the instance to keep running on its home node (§6).build_relocation_planallocates replacement frames withalloc_user_frame()on the current processor (x86/src/vmm.rs:495-520).Pool: PhysFrameAllocator. Inflation budget against a machine-wide floor (balloon.rs:354-358). Inflates withpool.allocate(balloon.rs:386). Reporting is onefree_runspass over the whole pool (balloon.rs:509-550).ReportedFrames(kernel/src/memory/reported.rs:45-68)KernelPhysFrameAllocator(kernel/src/memory/pmm.rs:38-216)PhysFrameAllocatoroverbuddy_system_allocator. Production use is only aPhantomData(kernel/src/exec/compaction.rs:108); otherwise tests (hosted/src/pmm_tests.rs).UserMemoryPool's role (decision 9.4).local_queues,local_ready_counts,idle,task_arenas, plus one global MPMC queue every processor drains, a global ready count and a global wake cursor. There is no queue-to-queue stealing today. The global queue is the balancing mechanism: a pushed task wakes one processor by cursor (executor.rs:1283-1310), and every processor pops it.InstanceSpawner(executor.rs:1192-1225) andProcessorTurns::begin(kernel/src/instance.rs:1103-1128)beginopens the owner scope under which the instance's commits happen.ProcessorSlotruntimes in oneBox<[...]>and AP kernel stacks fromallocate_aligned_zeroed(x86/src/smp.rs:347-434, 387). aarch64 slot array (aarch64/src/lib.rs:367-379).1.3 Processor identity the description must map from
ProcessorIdis the MADT entry order with the first entry as bootstrap: x86/src/smp.rs:347-420, following acpi-6.1.1src/platform/interrupt.rs:108-160("The first processor is the BSP"). The pre-heap count walks the same MADT (x86/src/lib.rs:604-634). The SRAT key is the APIC/x2APIC id.ProcessorIdis the bootstrap first, then Limine's MP order (aarch64/src/lib.rs:343-379), keyed by MPIDR. ACPI SRAT GICC affinity is keyed by ACPI processor UID, which MADT GICC maps to MPIDR (walked at aarch64/src/platform/acpi.rs:209-236). The devicetree cpuregis MPIDR.ProcessorIdis the hart id (riscv/src/lib.rs:642), and the cpu noderegis the hart id.ProcessorIdis a dense index everywhere the kernel uses it: secondaries start for0..configured_processors(kernel/src/lib.rs:1363-1367), and per-processor tables are indexed byid()(frame_slab.rs:213, executor.rs:803).2. Published prior art
Only the points that name a crate source line were read from source. Points marked (unsure) are to be checked against the Linux tree before the code that depends on them is written.
2.1 Linux memory
pg_data_tper node with zones inside it. Each node's zonelist is built bybuild_zonelists, which orders nodes withfind_next_best_nodebynode_distance. Equal-distance nodes are staggered by a load penalty, so different nodes fall back to different peers rather than all to the lowest id (the exact penalty formula: unsure). Only populated zones enter a zonelist, so a memoryless node's CPUs allocate from the nearest node with memory (local_memory_node). Required by: the per-node memory order, its tie rule, and memoryless-node handling (§5.2).struct per_cpu_pagesexists per zone, per CPU. Order-0 allocation pops the local CPU's pcp list of the zone being tried and refills from that zone's buddy inpcp->batchunits.free_unref_pagefrees onto the current CPU's pcp list of the page's own zone (page_zone(page)), andfree_pcppages_bulkdrains it back to that zone. A remotely freed page therefore stays its node's page. Required by: per-(processor, node) slab lists (§5.3).MPOL_DEFAULT, a page is allocated on the node of the CPU that faults it. Required by: allocation keyed on the executing processor (§5.2)./sys/devices/system/node/nodeN/numastatexposesnuma_hit,numa_miss,numa_foreign,local_node,other_nodeandinterleave_hit. Required by: the off-node counter (§7.2).setup_per_cpu_areas→pcpu_embed_first_chunkgroups CPUs by node, usingcpu_to_nodeand the distance callback, and allocates each group's units from that node's memory (memblock_alloc_nodeor the archpcpu_fc_alloc). Required by:PerProcessor<T>(§5.5).slit_valid()rejects a SLIT whose diagonal is notLOCAL_DISTANCE(10) or whose off-diagonal entry is not greater than 10; Linux then ignores the SLIT, where Helios fails fast. Without a distance table,node_distancedefaults toLOCAL_DISTANCE/REMOTE_DISTANCE(10/20) on both the ACPI and the OF paths. x86 hands CPUs with no SRAT entry out round-robin, and Linux gives up on NUMA when SRAT covers less than the e820 RAM (1 MiB tolerance). Helios fails fast on both instead (§3.1, §4.1).2.2 Linux scheduling
sched_init_numabuilds one NUMA sched-domain level per distinct distance value above the SMT/MC/PKG levels.newidle) balancing walks domains from the innermost outward, so a CPU pulls from its own LLC and node before a remote node.SD_NUMA, a largerimbalance_pct, and an allowed imbalance (imb_numa_nr/allow_numa_imbalance) that leaves small imbalances in place to keep tasks near memory (the thresholds: unsure).task_numa_fault, preferred node) migrates tasks and pages toward each other.Required by: steal order by distance (§6.2). Hinting-fault migration is not in #516's scope; the instance home is fixed (§6.3).
2.3 ACPI, as data
The ACPI fields below were checked against the struct layouts in acpi-6.1.1
src/sdt/srat.rs:112-228.u64locality count N followed by N×Nu8entries, where entryi*N+jis the distance from locality i to j (acpi-6.1.1src/sdt/slit.rs:8-11).2.4 Devicetree
From
Documentation/devicetree/bindings/numa.txt(not re-read for this design):numa-node-id(u32) appears oncpunodes, onmemorynodes and on devices; the value is the logical node id./distance-mapnode withcompatible = "numa-distance-map-v1"carriesdistance-matrix, a list of<node-a node-b distance>u32 triplets.of_numa_parse_distance_map_v1sets both. (Unsure whether the binding treats one direction as sufficient.)memory@…node per memory range, and QEMU emits one per NUMA node.3. The hal contract
3.1 New module
hal/src/numa.rsWhy each piece exists:
processor_nodeis a trait method rather than a stored array because the description is needed before the heap exists (x86/src/lib.rs:181-190, aarch64/src/lib.rs:560-563, riscv/src/lib.rs:676), and hal has no processor cap. x86 has none at all; riscv caps at 64 (riscv/src/lib.rs:170); aarch64 at 64 (aarch64/src/platform/mod.rs:54). A large cloud instance, where NUMA matters, exceeds 64.memory_affinityis what lets one shared helper tag regions (3.3). Backends do not each intersect ranges.SingleNodeis the issue's "one node, no special case": every consumer runs the same code over a one-element answer.NodeDistancein SLIT units comes from SLIT and the devicetree binding (§2.3, §2.4).UNIFORM_REMOTEis Linux's default for a missing table (§2.1). Here it is data, not a fallback: a platform that publishes no table says nothing about relative remoteness.cfg(target_arch), no consumer names. Node, distance and affinity are hardware properties, which satisfies §1 and thehal_layeringtest (kernel/tests/hal_layering.rs:4-46).3.2
hal/src/memory.rs: before and afterBefore (hal/src/memory.rs:1-11):
After:
MemoryMapis deleted, because it has no implementor or consumer (§1.1). Theunsafeconstructor moves the ownership promise thatinit_allocatorcurrently assumes (unsafe { region.as_mut() }, kernel/src/lib.rs:1212) to the backend that knows it holds.3.3
hal/src/boot.rs: one tagging helperThe new helper sits next to
usable_region_segments(hal/src/boot.rs:149-163):x86 and aarch64 both call it and delete their identical
boot_memory_regions(x86/src/lib.rs:691-714, aarch64/src/lib.rs:2189-2207). riscv'scollect_memory_regions(riscv/src/lib.rs:976-1004) calls it per memory-node segment. Required by: §1's duplication rule, and every backend needing node-tagged regions.3.4
hal/src/lib.rs:PlatformandProcessorTopologyBefore (hal/src/lib.rs:191-246):
Platform<Console, Cpu, Regions, WatchdogImpl>carriesmemory_regions: Regions, andPlatform::new(console, memory_regions, cpu).After:
Platform<Console, Cpu, WatchdogImpl>with no regions, andPlatform::new(console, cpu)/with_watchdog(console, cpu, watchdog). Memory enters the kernel through exactly one call:This replaces
(regions, processor_count: usize)at kernel/src/lib.rs:1275-1291.initon the bootstrap processor then requiresBOOT_INITIALIZING; theBOOT_UNINITIALIZED → bootstrap_initarm (kernel/src/lib.rs:1152-1154) is removed. hosted primes explicitly beforeinit, as every other backend already does. The reason for the change: a dead parameter on three backends (§1.1) plus a second entry would be two routes for one fact.ProcessorTopology(hal/src/lib.rs:60-97) is unchanged.initadds one assertion next to the existing processor-count assertion (kernel/src/lib.rs:1137-1142): the installedLocalityreports the same processor count.Cpu(hal/src/cpu.rs:245-389) is unchanged. The executing processor's node has to be answerable from drop paths, the allocator and fault context, exactly likecurrent_processor()(hal/src/cpu.rs:201-227). The kernel answers it withlocality.node_of(current_processor()), one load from an immutable table. ACpumethod would add a second route to that answer.3.5
hal/src/pmm.rs:PhysFrameAllocatorBefore (hal/src/pmm.rs:148-210):
allocate(count, zero),free_runs(min, max, visit),deallocate(range),stats().After:
Required by: the balloon (its only consumer, kernel/src/memory/balloon.rs:261-551), which must pick nodes and floors itself (§5.6). The module's SMP contract text (pmm.rs:8-13) is amended to say that each node's pool is fed from its own free lists and that a free returns to the frame's node.
3.6 Call sites that must follow
MemoryRegionPlatform::new/with_watchdogprime_bootstrap_allocatorPhysFrameAllocatorPhysFrameAllocator::uses, 355-947); hal/src/vmm.rs:558 (doc);KernelPhysFrameAllocatorand hosted/src/pmm_tests.rs (deleted, decision 9.4)4. Backends and the shared firmware crate
4.1 Where parsing lives today, and the new crate
Where it lives today:
AcpiTablesfour times: x86/src/lib.rs:617 (pre-heap MADT count), x86/src/smp.rs:333, x86/src/iommu.rs:177, x86/src/rtc.rs:121. It parses MADT (lib.rs:620-631, ioapic.rs:65-101), FADT, IVRS/DMAR and MCFG.PlatformTablesbuilt pre-heap (aarch64/src/platform/mod.rs:286-303), dispatching todt.rsoracpi.rs. Its module contract: built once on the bootstrap processor, then read-only (mod.rs:19-21).hal::entropy::device_tree_seed(hal/src/entropy.rs:10).New crate
firmware/, packagehelios-firmware:#![no_std]; dependencies:hal,acpi,fdt, all already in the lockfile.test-unitslist need the new crate added in the same change.The
AcpiNumareader:node_countis 1 and the answers areSingleNode's. That is the same code path with one node, not a branch in the kernel.MAX_NODESdistinct domains is refused.slit_valid, failing fast instead of ignoring).UNIFORM_REMOTE.The
DeviceTreeNumareader:numa-node-idvalues of cpu and memory nodes, sorted ascending.regequals the hardware id.memory@…node'sregranges with itsnuma-node-id./distance-mapdistance-matrixtriplets, written in both directions and validated as above. A missing pair or a missing map isUNIFORM_REMOTE.numa-node-idanywhere: one node.Required by: #516 "Backends", and §1 (one SRAT/SLIT reader for x86 and aarch64, one devicetree reader for aarch64 and riscv).
Blocker:
acpicrate defects. Theacpicrate (acpi-6.1.1, and still in 7.0.0-pre1, both read in the registry) has defects that make it unusable for this as published:MemoryAffinity::length()fills the high half frombase_address_high(acpi-6.1.1src/sdt/srat.rs:180-184). Any range above 4 GiB gets the wrong length.Slit::matrix_raw()checkssize_of::<Slit>() + num_entries * num_entrieswithnum_entries = N², so it checks N⁴ bytes (src/sdt/slit.rs:33-41). For N=2 it requires 60 bytes against a 48-byte table and returns an empty matrix for every multi-node SLIT.DistanceMatrix::distance()bounds-checks with<=and indexesi + j*N, transposed against its own doc comment (src/sdt/slit.rs:55-61).platform::numa::NumaInfoallocatesVecs (src/platform/numa.rs:14-19), so it cannot run pre-heap. The design does not use it; it usesSrat::entries()andSlit.Decision 9.1 covers how these are resolved.
4.2 Per backend
prime_bootstrap_allocator, the backend buildsAcpiNumafrom the tablesprocessor_countalready opens (x86/src/lib.rs:604-634). ItsProcessorIdentitieswalks the MADT in entry order, which is the orderAcpiPlatformassignsProcessorIds in (§1.3).usable_node_regions(..)and&numato prime.PhysicalOffsetAcpiHandler(x86/src/smp.rs:311-316), which maps by offset and allocates nothing.PlatformTables(mod.rs:286-332) gainsnuma(&self, ids) -> PlatformNuma, with two implementations of the trait, one per firmware path. The ids come from Limine's MP response in the existing bootstrap-first order (lib.rs:343-366), computed pre-heap fromMP_REQUESTlikeaarch64_processor_count(lib.rs:475-485).PlatformNumais a struct generic over the two readers, not an enum, per §3.2.DeviceTreeNumawith identity hart ids.collect_memory_regionswalks every memory node, which fixes the repair in 9.6.SingleNode::new(machine.processor_count()), primed in the bootstrap thread beforeinit.5. Kernel memory
5.1
Locality(new,kernel/src/memory/locality.rs)init_allocator, right after the first kernel-heap region is added. The heap is needed for the boxes, and the per-processor tables configured there need it (kernel/src/lib.rs:1247-1258).NumaTopologycontract clause in 3.1 is checked here, with a panic that names the processor, node pair or range at fault.(n − self − 1) mod node_count. That spreads equal-distance fallback the way Linux'sfind_next_best_nodestaggering does (§2.1), without load state.FrameNodes. One sortedArrayVec<(usize, NodeId), MAX_BOOT_MEMORY_REGIONS>holding the start of each run of same-node regions, merged across regions. Lookup ispartition_point. A single-node machine has one entry, so the lookup is trivially constant time.Localitylives inside the install-onceUserMemoryPool(published Release/Acquire throughUSER_MEMORY_POOL, user.rs:405, 447-475). That follows the existing install pattern rather than adding a static.5.2 Per-node pools
Initialization.
init_allocatorgroups the splitter's user shares byMemoryRegion::node()and callsFramePool::initializeonce per node that has memory (frame_pool.rs:44-85, unchanged). The buddy metadata therefore lands inside that node's own regions. The splitter receives the regions ordered bootstrap-node-first, so the kernel boot share is local to the processor that uses it (policy.rs:249-252 keeps taking it "from the front").Allocation, for a processor P on node N:
memory_order[N]:Notes on this path:
try_allocate_frame_onruns the same loop with try-locks only (user.rs:250-273).processor: Nonepath is resolved withcurrent_processor(), which hal publishes for exactly this use, the global allocator included (AGENTS §3.5; hal/src/cpu.rs:201-227). That deletes the shared fallback shard (frame_slab.rs:38).Kernel-heap lending.
lend_to_kernel_heapuses the executing processor's memory order. The kernel heap itself stays machine-wide (9.7).Free.
deallocate_bytes_onanddeallocatelook upframe_nodes. A single frame goes onto the freeing processor's list for that node (5.3); anything larger goes to that node's buddy.ReportedFrameslookups go to the node's bitmap.Stats.
stats()sums the nodes.stats_on(node)serves the per-node consumers (balloon,helios:system/stats).Largest block.
largest_servable_bytesreturns the maximum over nodes, probing in the caller's memory order.Relocation. A relocation replacement frame comes from the old frame's node and from no other. The new kernel API is
allocate_user_frame_on_node(node); x86build_relocation_plan(x86/src/vmm.rs:516) and the aarch64 and riscvrelocatepaths (aarch64/src/vmm.rs:1407, riscv/src/vmm.rs:1154) call it withnode_of(old_phys). A node with no free frame refuses the relocation rather than migrating the page.Out-of-memory, pressure, compaction and swap triggers stay machine-wide. Allocation falls through every node before failing, so machine-wide exhaustion is the true out-of-memory condition. That matches Linux, where OOM is reached only when the whole zonelist is exhausted.
5.3 Frame cache (
FrameSlabCache), reshapedBefore, there was one list per processor shard plus a fallback shard (frame_slab.rs:32-40). After:
lists[M]. A free of a frame on node M pusheslists[M]of the freeing processor's shard. This is Linux's per-zone per-cpu pageset (§2.1): a foreign free never touches the remote node's lock and never re-labels the frame.node_total_frames(M).div_ceil(64).div_ceil(processor_count). That is the existing 1/64 retain rule (frame_slab.rs:26, 200-206) per node; the divisor loses its+1because the fallback shard is gone. On one node, per-processor capacity grows by a factor of n/(n−1) (4/3 at four processors), the only single-node difference in this commit.try_allocate(fault path, try-lock).drain(node), which takes each shard's lock briefly, andcached_bytes(node), which reads the counts. The lock isIrqSafeMutex, as today (frame_slab.rs:8-10), because interrupt handlers allocate (§3.5 of AGENTS).CachePadded. Its lock and lists are written by its owner, and by a drainer under the lock.5.4 Fiber stacks and the fault reserve
frame_reserve. No structural change. Refills (frame_reserve.rs:287, 305) now go through the node order of the owner, so the frames a fiber-stack fault maps are local to the faulting processor. The shard array moves toPerProcessor(5.5). Its contract is unchanged: every word written by the owner, the shard on its own line (frame_reserve.rs:23-34).FiberStackSlot(fiber_stack.rs:201-211) gainsnode: AtomicU8, written by a cold claim with the claimant's node. The claimant commits the top page (fiber_stack.rs:530-544) and faults most of the rest.take_slot(SLOT_WARM)first scans for a warm slot on the claimant's node, then any warm slot, then a cold slot. Lowest-index-first is kept within each class (fiber_stack.rs:551-557).demand_commitsandannounced(fiber_stack.rs:228, 232) becomePerProcessor.nodeis written by the claiming processor (any processor) on a cold claim and read by any claimant's scan. It sits in the slot's existing padded block, which claim and release already write.5.5 Per-processor structures:
PerProcessor<T>(new,kernel/src/memory/per_processor.rs)NodeLocalArenabehind anIrqSafeMutex. The arena grows by one-way lends from its node's memory order, the same transferlend_to_kernel_heapmakes (user.rs:59-85), and is never freed. That matches the life of the structures it replaces: they are held in boot-timeOncestatics today (frame_slab.rs:39, executor.rs:55).newmay run on any processor, taking that node's arena lock; construction is rare.getis lock-free from anywhere.Tcontract says about its writers is thatT's own business.Adopters:
ProcessorRuntimeand AP stacksTask arenas. The bytes (
ArenaBytes, executor.rs:210-219) come from the owner'sNodeLocalArenainstead of the kernel heap.Accounting. The "Memory policy" boot line (kernel/src/lib.rs:1340-1348) gains
per_processor_bytes. On a single node this commit therefore movestask_arena_bytes × processorsfromkernel_heap_bytestoper_processor_byteswith the machine total unchanged. The paired lane is the check (§8).The structures' own later allocations (sockets inside a network shard, for example) still come from the machine-wide kernel heap (9.7).
5.6 Balloon and free-page reporting
free − total/PRESSURE_FLOOR_DIVISOR(balloon.rs:354-358, made per node) withallocate(node, ..). The guest keeps the same floor on every node, not just in sum. Taking from one node would push that node's instances off-node while the machine-wide number still looked healthy.deallocate(run)returns each run to its own node (balloon.rs:438).page_reporting_process.5.7 Contract summary for new and changed structures
LocalityNodePoolIrqSafeMutex);total_bytesFrameSlabShardNodeLocalArenaIrqSafeMutex), boot-time onlyPerProcessor<T>tableget(immutable pointer table)FiberStackSlot::nodeNodeQueue(§6)InstanceHome(§6)6. Scheduling
6.1 Queues
ExecutorGroup(executor.rs:101-113), after:A one-node machine has exactly today's single global queue.
6.2 Pop, steal and wake
Run loop (executor.rs:860-906):
scheduling_order[N][1..], by distance.Remote stealing happens as soon as the thief's local queue and own node are empty. That is #516's rule: prefer a victim on the thief's node, then remote by distance. It also matches Linux's innermost-domain-first idle balancing (§2.2).
Park test.
has_ready_work(executor.rs:989-992) tests the local count and every node's count withSeqCst. The handshake inidle's module docs is unchanged: a processor publishesParked, then re-tests everything it would drain.Wake on push to node M (replaces executor.rs:1283-1310):
node_processors[M], skipping the current processor.Parked.scheduling_order[M].6.3 Home node
Generic home.
GlobalSchedulergains a home:GlobalScheduler<CpuImpl, Home: TaskHome>, withtrait TaskHome { fn node(&self) -> NodeId; }. Variation through generics rather than an enum (§3.2). There are two implementations:FixedHome(NodeId):Spawner::spawn(executor.rs:1139-1146) uses the spawning processor's node. A kernel task stays near where it was created instead of drifting with its wakers.NoWeakArc<InstanceHome>:InstanceSpawner(executor.rs:1192-1225) carries the instance's cell. The launch path that builds the child's spawner (executor.rs:1206-1216) creates the cell and hands the sameArcto the registry entry (InstanceEntry, kernel/src/instance.rs:275-317).InstanceHomeis anAtomicU8: a node id plus a provisional bit.ProcessorTurns::begin(instance.rs:1103-1128) is the point where the owner scope opens and Wasmtime commits the instance's linear memory, during instantiation, throughAddressSpace::commiton this processor (owner.rs:1-15). On the instance's first turn,beginclears the provisional bit with a CAS and storesnode_of(current_processor()).Required by: #516 "an instance's home is the node its memory was committed on".
Fibers that resume on another processor. A store's turn is one global task; its fiber resumes on whichever processor polls the task. Every wake pushes to the home node's queue, so the task resumes on the home node unless that node is saturated and a remote processor steals it.
7. Observation and tests
7.1 Boot lines
These follow the existing "Kernel topology" line (kernel/src/lib.rs:1324-1328):
memory_bytesis the usable memory the node's pool was seeded with.processorsis a cpulist (0-1,4) formatted by aDisplaytype, throughtracingfields.nodes=1 distances=10and one node line.7.2
helios:system/statsIn wit/deps/helios-system/stats.wit (record
memoryat lines 41-47):numa_foreign/other_nodesplit. Its per-processor words are summed by node at sample time.inspector/src/stats_tui.rs.7.3 Host unit tests
All of these drive a synthetic plan over leaked host memory, using the existing
pool_atconstruction (kernel/src/memory/user.rs:642-665) andtest_processor_identity::set(kernel/src/lib.rs:1546-1562).Localityconstruction. Tie rotation; memory order skipping a memoryless node; each refused description (diagonal ≠ 10, off-diagonal ≤ 10, processor beyondnode_count, uncovered usable range) panicking with its message.usable_node_regions. One segment that crosses a node boundary splits in two. An uncovered byte panics with its range.firmware/. SRAT/SLIT and DTB bytes are built inside the tests from the spec layouts, so the test data is generated in the test rather than committed as binary fixtures. The tests cover:length_highdefect;distance-matrixgiven in one direction.7.4 QEMU arguments and the inspector knob
vmgains--numa-nodes <N>and--numa-distance <D>(and the config-file fieldsnuma_nodes,numa_distance), next tosmpandmemory(inspector/src/vm.rs:1373-1375, emitted at 4980-4981). AGENTS §5 says a missing knob is added to the inspector rather than passed through--qemu-arg(vm.rs:1403, 5028).--smpand--memory; anything else is refused by name.--numa-distanceemits-numa distfor every ordered pair, which makes QEMU publish a SLIT or/distance-map.For
--memory 2G --smp 4 --numa-nodes 2 --numa-distance 20, on x86-64q35, aarch64virt(DT and--acpi) and riscv64virtalike:Not verified against the lanes' QEMU builds, which stays open until the knob runs there:
virtderives its socket count from the NUMA node count and emits one PLIC and one memory node per socket;distance-mapwithout-numa dist.Smoke-lane assertion. Node count, processor lists and distances must match exactly. Each node's
memory_bytesmust fall in[size − 64 MiB, size], which absorbs firmware and kernel-image reservations.8. Staging: one PR, commits in order
Single-node behaviour is unchanged through commit 7. Commit 8 changes only memory accounting on one node (5.5). The paired lane (
bench-suite.yml, AGENTS §3.6) is the done-when check at the head.fix(riscv): read every devicetree memory node (own issue; 9.6)fix(riscv): pick the PLIC whose contexts name the bootstrap hart (own issue; 9.6)KernelPhysFrameAllocatorand its tests (9.4)numamodule,SingleNode,MemoryRegionstruct, deleteMemoryMap,usable_node_regions,Platformwithout regions,prime_bootstrap_allocator(regions, &numa). Every backend passesSingleNodeand node-0 regions; x86/aarch64boot_memory_regionsfolded into the hal helper. Kernel buildsLocality; boot lines (7.1).firmware/crate with host tests; not yet wiredPhysFrameAllocatorper node + per-node pools + per-(processor, node) slab lists + distance-ordered allocation + off-node counters + node-preserving relocation + balloon/reporting per node + tests 7.3.1-4TaskHome,InstanceHome, steal order and wake routing + tests 7.3.5helios:system/statsper-node record and bindings, inspector stats viewPerProcessor<T>+NodeLocalArena; adopters; task arenas; fiber warm-slot node preference--numa-nodes/--numa-distance; smoke-lane two-node boots (9.5)Independent implementers, without file overlap, once commit 2 has landed:
firmware/);Commits 4 and 5 share only the read-only
Localityaccessor added in commit 2.Sequencing that cannot be split:
9. Risks and open decisions
9.1 The
acpicrate's SRAT/SLIT defects (4.1).MemoryAffinity::lengthhigh half;matrix_rawbound of N² bytes;distancebound<and indexi*N+j), then bump to the release that carries it.mainstill carries all three as of 2026-11-10, with no issue or PR open against them.9.2 Frame cache shape.
9.3 Instance home before the first turn.
begin.9.4
KernelPhysFrameAllocator.PhantomData(compaction.rs:108). Keeping it would mean porting a second, unused frame allocator to the per-node contract (§3.1, no duplicated paths).9.5 CI lanes.
9.6 Pre-existing riscv defects a two-node riscv boot hits.
Fdt::memory()returns the first node namedmemoryonly (fdt-0.1.5src/lib.rs:238-239,find_nodedoc at 277-282).collect_memory_regions(riscv/src/lib.rs:641, 976-1004) would silently drop node 1's memory.discover_plic_contexttakes the first PLIC node (riscv/src/net/mod.rs:376). On a two-socketvirtthat may be the other socket's PLIC, which has no context for the bootstrap hart (unverified which PLIC QEMU writes first). The backend then refuses the UART (riscv/src/lib.rs:846-853).9.7 Kernel heap stays machine-wide.
PerProcessorcovers the per-processor blocks. A node-aware kernel heap (Linuxkmalloc_node) is a separate change with its own reserve semantics.9.8 Wasmtime table pool.
funcreftables sit on the build processor's node and are read on everycall_indirect.PoolingAllocationConfighook called on table-slot allocation with the slot's range, so the embedder can commit it on the current processor.9.9 Eager remote stealing.
Not yet verified: the QEMU behaviours listed in 7.4 and 9.6, the Linux details marked (unsure) in §2, and the pinned Wasmtime revision's
linear_memory_keep_residentdefault (1.2).refactor(kernel): drop ReportedFrames::take, whose only caller was th…
test(kernel): drive ReportedFrames through take_bytes
feat(hal)!: memory regions carry their node, and a NUMA description r…
feat(firmware): read NUMA locality from a devicetree
docs(agents): place firmware/ in the tree and in test-units
lexoliu commentedon Nov 12, 2026
The aarch64 image of CI run 43160598414 (811651e) booted under HVF on an M1 host, device tree, 4 vCPUs and 2G, with and without
--numa-nodes 2 --numa-distance 20. Both reach the guest shell.One node:
Two nodes:
The device-tree path reads the layout QEMU publishes: two processors per node, the user pool split across both, the distance map as given. The ACPI description still reports one node.
lexoliu commentedon Nov 13, 2026
#598 lands the first three items: the two-node boots in every smoke lane (riscv64 and aarch64 from the device tree, x86-64 and aarch64 from ACPI), the two-node allocation tests in
kernel/src/memory/user.rs, and two single-node paired runs with every compared row unchanged (43337651395, 43367031679).What keeps this open is the last item. Every CI runner and every development machine is one physical node, so placement is proven and its speed is not: the measurement needs a host with more than one node.