NUMA topology initialization and deterministic placement helpers — core interface. More...

import std;
import lib.error;
import arch.s390x.init.zxfl.protocol;
import zxfoundation.memory.numa.types;
import zxfoundation.base.types;

Include dependency graph for core.cxxm:

Functions
auto	zxfoundation::memory::numa::cpu_distance (u16 cpu_a, u16 cpu_b) noexcept -> u8
	Return the distance between two logical CPUs by way of their assigned NUMA nodes.
auto	zxfoundation::memory::numa::generation () noexcept -> u64
	Return the current topology generation.
auto	zxfoundation::memory::numa::has_loader_memory_evidence () noexcept -> bool
	Report whether topology contains loader-provided memory evidence.
auto	zxfoundation::memory::numa::init (const arch::s390x::init::zxfl::protocol &protocol) noexcept -> std::expected< void, lib::kernel_error >
	Initialize immutable NUMA topology from the ZXFL boot protocol.
auto	zxfoundation::memory::numa::initialized () noexcept -> bool
	Report whether NUMA topology has been initialized.
auto	zxfoundation::memory::numa::node_at (u8 node_id) noexcept -> std::expected< const node_topology *, lib::kernel_error >
	Read one NUMA node record.
auto	zxfoundation::memory::numa::node_count () noexcept -> u8
	Count NUMA node records known to the topology table.
auto	zxfoundation::memory::numa::node_distance (u8 node_a, u8 node_b) noexcept -> u8
	Read NUMA distance between two nodes (units: 10 local … 255 max).
auto	zxfoundation::memory::numa::node_for_cpu (u16 cpu_id) noexcept -> std::expected< u8, lib::kernel_error >
	Resolve a logical CPU to its preferred NUMA node.
auto	zxfoundation::memory::numa::node_for_pfn (u64 pfn) noexcept -> std::expected< u8, lib::kernel_error >
	Resolve a page-frame number to a NUMA node.
auto	zxfoundation::memory::numa::node_for_phys (u64 phys) noexcept -> std::expected< u8, lib::kernel_error >
	Resolve a physical address to a NUMA node.
auto	zxfoundation::memory::numa::node_of_cpu (u16 cpu_id) noexcept -> u8
	Return the NUMA node id assigned to a logical CPU.
auto	zxfoundation::memory::numa::resolve_policy (const allocation_policy &policy, u8 local_node) noexcept -> std::expected< placement_result, lib::kernel_error >
	Resolve an allocation policy into an initial placement decision.
auto	zxfoundation::memory::numa::slit_install (const slit_matrix &matrix, bool stsi_ok) noexcept -> void
	Install a fully-resolved SLIT matrix from an outside evidence.
auto	zxfoundation::memory::numa::slit_load_synthetic () noexcept -> void
	Sealed-synthetic fallback installer.
auto	zxfoundation::memory::numa::slit_source_kind () noexcept -> u32
	Diagnostics: report the SLIT table source.
auto	zxfoundation::memory::numa::uses_synthetic_fallback () noexcept -> bool
	Report whether the current topology had to synthesize the boot node.

Detailed Description

NUMA topology initialization and deterministic placement helpers — core interface.

SPDX-License-Identifier: Apache-2.0

Function Documentation

◆ generation()

auto zxfoundation::memory::numa::generation ( ) ->u64

nodiscardexportnoexcept

Return the current topology generation.

Returns: Monotonic generation incremented after successful initialization.

Note: Later hotplug or topology-recovery waves may increment this value again.

◆ has_loader_memory_evidence()

auto zxfoundation::memory::numa::has_loader_memory_evidence ( ) ->bool

nodiscardexportnoexcept

Report whether topology contains loader-provided memory evidence.

Returns: true when at least one node record was derived from ZXFL usable-memory topology.

Note: Later kernel self-discovery should refine this with direct machine topology records.

◆ init()

auto zxfoundation::memory::numa::init ( const arch::s390x::init::zxfl::protocol & protocol ) ->std::expected< void, lib::kernel_error >

exportnoexcept

Initialize immutable NUMA topology from the ZXFL boot protocol.

Parameters

[in] protocol Loader-supplied boot protocol containing memory and CPU topology evidence.

Returns: Success when at least the deterministic bootstrap fallback node exists.

Note: The current implementation consumes ZXFL records only; later boot-topology hardening may replace the evidence with direct STSI/SCLP records.

Warning: This function must run before AP release and before node-owned allocator state is initialized.

Here is the call graph for this function:

◆ initialized()

auto zxfoundation::memory::numa::initialized ( ) ->bool

nodiscardexportnoexcept

Report whether NUMA topology has been initialized.

Returns: true after init() has completed successfully.

Note: The topology table is immutable after successful initialization in this migration wave.

◆ node_at()

auto zxfoundation::memory::numa::node_at ( u8 node_id ) ->std::expected< constnode_topology *, lib::kernel_error >

nodiscardexportnoexcept

Read one NUMA node record.

Parameters

[in] node_id Node identifier to inspect.

Returns: Pointer to the immutable node record, or a kernel error.

Warning: The returned pointer remains valid only while the topology generation is unchanged.

◆ node_count()

auto zxfoundation::memory::numa::node_count ( ) ->u8

nodiscardexportnoexcept

Count NUMA node records known to the topology table.

Returns: Number of non-empty node records.

Warning: A known node may be degraded and may not currently contain allocatable memory.

◆ node_distance()

auto zxfoundation::memory::numa::node_distance	(	u8	node_a,
		u8	node_b )->u8

nodiscardexportnoexcept

Read NUMA distance between two nodes (units: 10 local … 255 max).

Parameters

[in]	node_a	Source node id.
[in]	node_b	Destination node id.

Returns: Distance from the SLIT cache, or 255 when either id is out of range.

◆ node_for_cpu()

auto zxfoundation::memory::numa::node_for_cpu ( u16 cpu_id ) ->std::expected< u8, lib::kernel_error >

nodiscardexportnoexcept

Resolve a logical CPU to its preferred NUMA node.

Parameters

[in] cpu_id Kernel logical CPU identifier.

Returns: Preferred NUMA node identifier for the CPU.

Note: The mapping is derived from ZXFL CPU topology evidence and is stable until topology generation changes.

◆ node_for_pfn()

auto zxfoundation::memory::numa::node_for_pfn ( u64 pfn ) ->std::expected< u8, lib::kernel_error >

nodiscardexportnoexcept

Resolve a page-frame number to a NUMA node.

Parameters

[in] pfn Page-frame number using the 4 KiB base page granule.

Returns: NUMA node identifier containing the frame, or a kernel error.

◆ node_for_phys()

auto zxfoundation::memory::numa::node_for_phys ( u64 phys ) ->std::expected< u8, lib::kernel_error >

nodiscardexportnoexcept

Resolve a physical address to a NUMA node.

Parameters

[in] phys Physical address to classify.

Returns: NUMA node identifier containing the address, or a kernel error.

Note: Sparse or discontiguous firmware regions fall back to the first encompassing node range.

◆ node_of_cpu()

auto zxfoundation::memory::numa::node_of_cpu ( u16 cpu_id ) ->u8

nodiscardexportnoexcept

Return the NUMA node id assigned to a logical CPU.

Parameters

[in] cpu_id Logical CPU id.

Returns: NUMA node id (NUMA_NODE_BOOT when out of range).

◆ resolve_policy()

auto zxfoundation::memory::numa::resolve_policy	(	const allocation_policy &	policy,
		u8	local_node )->std::expected< placement_result, lib::kernel_error >

nodiscardexportnoexcept

Resolve an allocation policy into an initial placement decision.

Parameters

[in]	policy	Caller-supplied placement policy.
[in]	local_node	Local CPU or domain preferred node.

Returns: Selected node and fallback metadata, or a kernel error.

Note: Deep PMM integration will consume this resolver when node-owned zones are introduced.

Warning: This function does not allocate memory and does not reserve allocator watermarks.

◆ slit_install()

auto zxfoundation::memory::numa::slit_install	(	const slit_matrix &	matrix,
		bool	stsi_ok )->void

exportnoexcept

Install a fully-resolved SLIT matrix from an outside evidence.

Install a fully-resolved SLIT matrix from an outside evidence probe (typically sched_node_distance's STSI 15.1.x walk).

Parameters

[in]	matrix	16×16 distance matrix populated by the caller.
[in]	stsi_ok	True when the matrix was built from real machine topology (STSI), false when it is a synthetic fallback.

◆ slit_load_synthetic()

auto zxfoundation::memory::numa::slit_load_synthetic ( ) ->void

exportnoexcept

Sealed-synthetic fallback installer.

Sealed-synthetic fallback installer — mirrors Linux's build_synthetic_slit(): 10 local / 20 boot-adjacent / 40 fully-remote edges. Used by init() and by callers that detect STSI unavailability before the scheduler boots.

Here is the call graph for this function:

◆ slit_source_kind()

auto zxfoundation::memory::numa::slit_source_kind ( ) ->u32

nodiscardexportnoexcept

Diagnostics: report the SLIT table source.

Returns: 0 = uninitialized, 1 = STSI 15.1.x, 2 = synthetic, 3 = degraded.

◆ uses_synthetic_fallback()

auto zxfoundation::memory::numa::uses_synthetic_fallback ( ) ->bool

nodiscardexportnoexcept

Report whether the current topology had to synthesize the boot node.

Returns: true when the deterministic single-node fallback is active.

Note: This is safe for allocation and records that no explicit multi-node placement evidence was available.

ZXFoundation™ 26h2

Functions

Detailed Description

Function Documentation

◆ generation()

◆ has_loader_memory_evidence()

◆ init()

◆ initialized()

◆ node_at()

◆ node_count()

◆ node_distance()

◆ node_for_cpu()

◆ node_for_pfn()

◆ node_for_phys()

◆ node_of_cpu()

◆ resolve_policy()

◆ slit_install()

◆ slit_load_synthetic()

◆ slit_source_kind()

◆ uses_synthetic_fallback()