core.cxxm File Reference

Physical Memory Manager — core interface. More...

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

Include dependency graph for core.cxxm:

Data Structures
class	zxfoundation::memory::pmm::transaction
	Atomic multi-folio allocation transaction. More...

Typedefs
using	zxfoundation::memory::pmm::allocation_retry_fn = auto (*)(u8 node, u32 target_pages) noexcept -> u32
	Callback invoked once after a sleepable allocation exhausts all eligible node zones.

Functions
auto	zxfoundation::memory::pmm::alloc (const allocation_request &request) noexcept -> std::expected< allocation_result, lib::kernel_error >
	Allocate a single folio.
auto	zxfoundation::memory::pmm::alloc (u32 order, zone z, purpose p, page_init init) noexcept -> std::expected< folio_embryo, lib::kernel_error >
	Allocate a single folio.
auto	zxfoundation::memory::pmm::desc_of_checked (u64 phys) noexcept -> std::expected< frame_desc *, lib::kernel_error >
	Fail-closed frame-descriptor accessor.
auto	zxfoundation::memory::pmm::frame_clear_mapping_metadata (u64 phys) noexcept -> std::expected< void, lib::kernel_error >
	Clear the authority identity stamped on one physical frame.
auto	zxfoundation::memory::pmm::frame_desc_of (u64 phys) noexcept -> frame_desc *
	Return a pointer to the frame_desc for a physical address.
auto	zxfoundation::memory::pmm::frame_node_of (u64 phys) noexcept -> std::expected< u8, lib::kernel_error >
	Return the NUMA node id recorded for a frame.
auto	zxfoundation::memory::pmm::frame_object_generation_of (u64 phys) noexcept -> std::expected< u32, lib::kernel_error >
	Resolve the SCOMS generation paired with a frame authority id.
auto	zxfoundation::memory::pmm::frame_object_id_of (u64 phys) noexcept -> std::expected< u32, lib::kernel_error >
	Resolve the SCOMS memory_object_id that authorizes a frame.
auto	zxfoundation::memory::pmm::frame_ref (u64 phys) noexcept -> std::expected< u16, lib::kernel_error >
	Atomically increment a frame's refcount.
auto	zxfoundation::memory::pmm::frame_refcount (u64 phys) noexcept -> std::expected< u16, lib::kernel_error >
	Return the current atomic reference count of a frame.
auto	zxfoundation::memory::pmm::frame_release_pin (u64 phys) noexcept -> std::expected< bool, lib::kernel_error >
	Release one order-zero mapping pin and return the frame.
auto	zxfoundation::memory::pmm::frame_set_mapping_metadata (u64 phys, u32 object_id, u32 object_generation, bool writable) noexcept -> std::expected< void, lib::kernel_error >
	Stamp the SCOMS memory_object id that authorizes this frame.
auto	zxfoundation::memory::pmm::frame_unref (u64 phys) noexcept -> std::expected< u16, lib::kernel_error >
	Atomically decrement a frame's refcount.
auto	zxfoundation::memory::pmm::frame_validate_mapping (u64 phys_start, u64 length, u32 object_id, u32 object_generation) noexcept -> std::expected< void, lib::kernel_error >
	Validate that a physical range is owned by one SCOMS object.
auto	zxfoundation::memory::pmm::free (folio_active f) noexcept -> void
	Return a folio to the allocator.
auto	zxfoundation::memory::pmm::free_page_count () noexcept -> u64
	Advisory free page count (sum across all zones).
auto	zxfoundation::memory::pmm::init (const arch::s390x::init::zxfl::protocol &proto) noexcept -> void
	Initialize the PMM from the ZXFL boot protocol.
auto	zxfoundation::memory::pmm::install_allocation_retry (allocation_retry_fn callback) noexcept -> std::expected< void, lib::kernel_error >
	Install the allocation-pressure reclaim callback.
auto	zxfoundation::memory::pmm::max_pfn () noexcept -> u64
auto	zxfoundation::memory::pmm::reserve (u64 phys, u32 order) noexcept -> void
	Mark a physical range as permanently reserved (runtime call).
auto	zxfoundation::memory::pmm::total_page_count () noexcept -> u64
	Total managed page count (sum across all zones).

Variables
constexpr u32	zxfoundation::memory::pmm::TXN_MAX = 16

Detailed Description

Physical Memory Manager — core interface.

SPDX-License-Identifier: Apache-2.0

Function Documentation

alloc() [1/2]

auto zxfoundation::memory::pmm::alloc ( const allocation_request & request ) ->std::expected< allocation_result, lib::kernel_error >

nodiscardexportnoexcept

Allocate a single folio.

Parameters

[in]

request

Node-aware allocation request.

Returns

Allocation result containing the folio and resolved placement metadata.

Note

Order-zero through PCP_MAX_ORDER allocations attempt the current CPU's node-local PCP first.

Warning

Allocation is forbidden in MCCK context and multi-page allocation is forbidden in hard IRQ context.

alloc() [2/2]

auto zxfoundation::memory::pmm::alloc ( u32 order, zone z, purpose p, page_init init )->std::expected< folio_embryo, lib::kernel_error >

nodiscardexportnoexcept

Allocate a single folio.

Parameters

[in]	order	Buddy order (0–MAX_ORDER).
[in]	z	Zone constraint.
[in]	p	Semantic purpose annotation.
[in]	init	Initialization policy.

Returns

folio_embryo on success, kernel_error on failure.

desc_of_checked()

auto zxfoundation::memory::pmm::desc_of_checked ( u64 phys ) ->std::expected< frame_desc *, lib::kernel_error >

nodiscardexportnoexcept

Fail-closed frame-descriptor accessor.

Parameters

[in]

phys

Physical address (lower PAGE_SHIFT bits are ignored).

Returns

Pointer into the frame descriptor table, or a kernel_error when the PMM is uninitialized or phys is outside the managed physical range.

frame_desc_of()

auto zxfoundation::memory::pmm::frame_desc_of ( u64 phys ) ->frame_desc *

nodiscardexportnoexcept

Return a pointer to the frame_desc for a physical address.

Parameters

[in]

phys

Physical address (lower PAGE_SHIFT bits are ignored).

Returns

Pointer into the frame descriptor table, or nullptr if the address is out of range or init() has not been called.

frame_node_of()

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

nodiscardexportnoexcept

Return the NUMA node id recorded for a frame.

Parameters

[in]

phys

Physical frame address.

Returns

NUMA node id, or a checked physical-address error.

frame_object_id_of()

auto zxfoundation::memory::pmm::frame_object_id_of ( u64 phys ) ->std::expected< u32, lib::kernel_error >

nodiscardexportnoexcept

Resolve the SCOMS memory_object_id that authorizes a frame.

Parameters

[in]

phys

Physical frame address.

Returns

SCOMS id, or KOBJECT_ID_INVALID when the frame is not bound to a memory authority (buddy-owned, reserved, page-table).

frame_ref()

auto zxfoundation::memory::pmm::frame_ref ( u64 phys ) ->std::expected< u16, lib::kernel_error >

nodiscardexportnoexcept

Atomically increment a frame's refcount.

Parameters

[in]

phys

Physical base address of the frame.

Returns

New refcount on success, kernel_error on invalid address.

frame_refcount()

auto zxfoundation::memory::pmm::frame_refcount ( u64 phys ) ->std::expected< u16, lib::kernel_error >

nodiscardexportnoexcept

Return the current atomic reference count of a frame.

Parameters

[in]

phys

Physical frame address.

Returns

Reference count or a checked physical-address error.

frame_release_pin()

auto zxfoundation::memory::pmm::frame_release_pin ( u64 phys ) ->std::expected< bool, lib::kernel_error >

nodiscardexportnoexcept

Release one order-zero mapping pin and return the frame.

Returns

True when this call returned the frame to buddy/PCP, false when another pin still owns it.

Note

The frame descriptor supplies the NUMA node and physical zone

Returns

True when this call returned the frame to buddy/PCP, false when another pin still owns it.

frame_set_mapping_metadata()

auto zxfoundation::memory::pmm::frame_set_mapping_metadata ( u64 phys, u32 object_id, u32 object_generation, bool writable )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Stamp the SCOMS memory_object id that authorizes this frame.

Parameters

[in]	phys	Physical frame address.
[in]	object_id	SCOMS id of the authoritative memory_object (typically a vm_region's storage_object grant, or KOBJECT_ID_INVALID to clear).
[in]	object_generation	SCOMS generation paired with object_id.
[in]	writable	True when the frame backs a writable mapping.

Returns

Success or a checked physical-address error.

frame_unref()

auto zxfoundation::memory::pmm::frame_unref ( u64 phys ) ->std::expected< u16, lib::kernel_error >

nodiscardexportnoexcept

Atomically decrement a frame's refcount.

Parameters

[in]

phys

Physical base address of the frame.

Returns

New refcount on success, kernel_error on invalid address.

frame_validate_mapping()

auto zxfoundation::memory::pmm::frame_validate_mapping ( u64 phys_start, u64 length, u32 object_id, u32 object_generation )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate that a physical range is owned by one SCOMS object.

Parameters

[in]	phys_start	Page-aligned physical range start.
[in]	length	Range length in bytes.
[in]	object_id	Required SCOMS id (must match frame_desc::object_id).
[in]	object_generation	Required paired SCOMS generation.

Returns

Success only when every page carries the exact live object identity and generation, and is not MCCK-offline.

free()

auto zxfoundation::memory::pmm::free ( folio_active f ) ->void

exportnoexcept

Return a folio to the allocator.

Parameters

[in]

f

The folio to free. Must not be empty.

init()

auto zxfoundation::memory::pmm::init ( const arch::s390x::init::zxfl::protocol & proto ) ->void

exportnoexcept

Initialize the PMM from the ZXFL boot protocol.

Parameters

[in]

proto

Validated ZXFL boot protocol.

reserve()

auto zxfoundation::memory::pmm::reserve ( u64 phys, u32 order )->void

exportnoexcept

Mark a physical range as permanently reserved (runtime call).

Parameters

[in]	phys	Start of the range (page-aligned).
[in]	order	log2 of the number of pages to reserve.