DGP isolation lifecycle and authorization implementation. More...

import std;
import arch.s390x.mmu.types;
import zxfoundation.base.config;
import zxfoundation.sched.policy;
import zxfoundation.sync.lockable;
import zxfoundation.dgp.domain.types;
import zxfoundation.dgp.memory_contract;
import lib.error;
import zxfoundation.dgp.isolation.types;
import zxfoundation.base.typestate;
import zxfoundation.base.types;

Include dependency graph for core.cxx:

Data Structures
class	zxfoundation::dgp::isolation::detail::storage_key_lock_guard

Enumerations
enum class	zxfoundation::dgp::isolation::lifecycle_state
	Unified lifecycle states for ALL typestate-tracked resources. More...

Functions
auto	zxfoundation::dgp::isolation::activate_domain (lifecycle_state &state, arch::s390x::mmu::typed_asce< arch::s390x::mmu::dat_level::region_1 > asce, u64 root_phys, u8 storage_key) noexcept -> std::expected< void, lib::kernel_error >
	Activate a sealed DGP isolation domain.
auto	zxfoundation::dgp::isolation::detail::allocate_storage_key (u8 requested) noexcept -> std::expected< u8, lib::kernel_error >
auto	zxfoundation::dgp::isolation::begin_portal_teardown (lifecycle_state &state, std::atomic< u16 > &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
	Record that a portal authority is leaving the active DGP set.
auto	zxfoundation::dgp::isolation::begin_portal_teardown (lifecycle_state &state, u16 &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
auto	zxfoundation::dgp::isolation::begin_storage_key_revocation (lifecycle_state &state, skey_revocation_state &storage_key_state, std::atomic< u16 > &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
	Begin revocation of the storage-key authority attached to a DGP domain.
auto	zxfoundation::dgp::isolation::begin_storage_key_revocation (lifecycle_state &state, skey_revocation_state &storage_key_state, u16 &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
auto	zxfoundation::dgp::isolation::bind_asce_root (isolation_domain_state &state, lifecycle_state current_ls, arch::s390x::mmu::typed_asce< arch::s390x::mmu::dat_level::region_1 > asce, u64 root_phys) noexcept -> std::expected< void, lib::kernel_error >
	Attach committed DAT root state to a DGP isolation domain.
auto	zxfoundation::dgp::isolation::complete_storage_key_revocation (lifecycle_state &state, u8 &storage_key, u32 &storage_key_generation, skey_revocation_state &storage_key_state) noexcept -> std::expected< void, lib::kernel_error >
	Complete storage-key revocation after required translation invalidation is done.
auto	zxfoundation::dgp::isolation::create_domain (u32 domain_id, const isolation_policy &policy) noexcept -> std::expected< isolation_domain_state, lib::kernel_error >
	Create initial DGP isolation state for a domain.
auto	zxfoundation::dgp::isolation::destroy_domain (lifecycle_state &state, u8 &storage_key, u32 &storage_key_generation, skey_revocation_state &storage_key_state, std::atomic< u16 > &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
	Destroy DGP isolation state for a domain.
auto	zxfoundation::dgp::isolation::destroy_domain (lifecycle_state &state, u8 &storage_key, u32 &storage_key_generation, skey_revocation_state &storage_key_state, u16 &revocation_epoch) noexcept -> std::expected< void, lib::kernel_error >
auto	zxfoundation::dgp::isolation::detail::generic_invalid_arg () noexcept -> lib::kernel_error
auto	zxfoundation::dgp::isolation::init () noexcept -> void
	Initialize the DGP isolation clean core.
auto	zxfoundation::dgp::isolation::detail::mask_is_valid (zxfoundation::sched::sched_mask mask, u32 limit) noexcept -> bool
auto	zxfoundation::dgp::isolation::detail::memory_out_of_memory () noexcept -> lib::kernel_error
auto	zxfoundation::dgp::isolation::detail::release_storage_key (u8 key) noexcept -> u32
auto	zxfoundation::dgp::isolation::revoke_domain_rights (zxfoundation::dgp::domain::domain &d, dgp::isolation::isolation_rights drop_mask) noexcept -> std::expected< void, lib::kernel_error >
	Lazy revocation of DGP rights on a domain.
auto	zxfoundation::dgp::isolation::detail::storage_key_generation (u8 key) noexcept -> u32
auto	zxfoundation::dgp::isolation::validate_gate_entry (u32 caller_domain_id, u32 gate_id, dgp::isolation::isolation_rights requested) noexcept -> std::expected< void, lib::kernel_error >
	Validate entry into a DGP gate chokepoint (structural validation only).
auto	zxfoundation::dgp::isolation::validate_portal (u32 source_domain_id, u32 target_domain_id, u64 va_start, u64 va_end, dgp::isolation::isolation_rights requested) noexcept -> std::expected< void, lib::kernel_error >
	Validate creation or use of a DGP portal.
auto	zxfoundation::dgp::isolation::validate_scheduler_admission (const lifecycle_state state, u64 root_phys, u64 asce_raw) noexcept -> std::expected< void, lib::kernel_error >
	Validate that a DGP domain may be admitted to a CPU run queue.
auto	zxfoundation::dgp::isolation::validate_scheduler_policy (const lifecycle_state state, const zxfoundation::sched::sched_policy &policy, bool has_rt_authority) noexcept -> std::expected< zxfoundation::sched::sched_admission_result, lib::kernel_error >
	Validate a scheduler policy against DGP authority and basic safety invariants.

Variables
static std::atomic< bool >	zxfoundation::dgp::isolation::detail::g_isolation_initialized {false}
static u32	zxfoundation::dgp::isolation::detail::g_storage_key_generation [STORAGE_KEY_COUNT] {}
static std::atomic< u32 >	zxfoundation::dgp::isolation::detail::g_storage_key_lock {0U}
static bool	zxfoundation::dgp::isolation::detail::g_storage_key_used [STORAGE_KEY_COUNT] {}

Detailed Description

DGP isolation lifecycle and authorization implementation.

SPDX-License-Identifier: Apache-2.0

Enumeration Type Documentation

◆ lifecycle_state

enum class zxfoundation::base::lifecycle_state : u8

strong

Unified lifecycle states for ALL typestate-tracked resources.

Every SCOMS-managed object, every folio, and every slab cache uses exactly these states. No subsystem may define its own.

Function Documentation

◆ activate_domain()

auto zxfoundation::dgp::isolation::activate_domain	(	lifecycle_state &	state,
		arch::s390x::mmu::typed_asce< arch::s390x::mmu::dat_level::region_1 >	asce,
		u64	root_phys,
		u8	storage_key )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Activate a sealed DGP isolation domain.

Parameters

[in]	state	Isolation state to activate.
[in]	asce	Typed region-first ASCE constructed from the committed DAT root.
[in]	root_phys	Physical address of the committed region-first root table.
[in]	storage_key	The domain's hardware storage key.

Returns: Success when the domain transitions to active.

Note: Activation requires committed ASCE root metadata before scheduler admission.

Warning: Active domains must deny new gate and portal entries before destruction.

Parameters

[in]	state	Isolation state to activate.
[in]	asce	Typed region-first ASCE constructed from the committed DAT root.
[in]	root_phys	Physical address of the committed region-first root table.
[in]	storage_key	The domain's hardware storage key.

Returns: Success when the domain transitions to active.

◆ begin_portal_teardown()

auto zxfoundation::dgp::isolation::begin_portal_teardown	(	lifecycle_state &	state,
		std::atomic< u16 > &	revocation_epoch )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Record that a portal authority is leaving the active DGP set.

Parameters

[in,out]	state	Isolation state for the source domain that held the portal.
[in,out]	revocation_epoch	Revocation epoch counter.

Returns: Success when one active portal reference was converted into revocation progress.

Note: Portal teardown must purge ALB state before the corresponding ALE can be reused.

Warning: This function only updates DGP metadata; callers still destroy hardware access-list entries.

Parameters

[in,out]	state	Isolation state for the source domain that held the portal.
[in,out]	revocation_epoch	Revocation epoch counter.

Returns: Success when one active portal reference was converted into revocation progress.

◆ begin_storage_key_revocation()

auto zxfoundation::dgp::isolation::begin_storage_key_revocation	(	lifecycle_state &	state,
		skey_revocation_state &	storage_key_state,
		std::atomic< u16 > &	revocation_epoch )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Begin revocation of the storage-key authority attached to a DGP domain.

Parameters

[in,out] state Isolation state whose key is entering the draining phase.

Returns: Success when no live gate or portal authority can still observe the key.

Note: Storage-key reuse is delayed until callers have invalidated DAT and ALB state associated with the domain.

Warning: This function does not modify hardware storage keys; it records the software authority transition.

Parameters

[in,out] state Isolation state whose key is entering the draining phase.

Returns: Success when no live gate or portal authority can still observe the key.

◆ bind_asce_root()

auto zxfoundation::dgp::isolation::bind_asce_root	(	isolation_domain_state &	state,
		lifecycle_state	current_ls,
		arch::s390x::mmu::typed_asce< arch::s390x::mmu::dat_level::region_1 >	asce,
		u64	root_phys )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Attach committed DAT root state to a DGP isolation domain.

Parameters

[in]	state	Isolation state to update.
[in]	current_ls	Current lifecycle state (from ko.state) — must be sealed.
[in]	asce	Typed region-first ASCE constructed from the committed DAT root.
[in]	root_phys	Physical address of the committed region-first root table.

Returns: Success when the state can accept the ASCE root metadata.

Note: The IBM PoP defines ASCE contents as hardware-consumed DAT state; this helper records ownership and does not load a control register.

Warning: The caller remains responsible for allocating and freeing the DAT table through the MMU transaction path.

Parameters

[in]	state	Isolation state to update.
[in]	current_ls	Current lifecycle state (from ko.state) — must be sealed.
[in]	asce	Typed region-first ASCE constructed from the committed DAT root.
[in]	root_phys	Physical address of the committed region-first root table.

Returns: Success when the state can accept the ASCE root metadata.

◆ complete_storage_key_revocation()

auto zxfoundation::dgp::isolation::complete_storage_key_revocation	(	lifecycle_state &	state,
		u8 &	storage_key,
		u32 &	storage_key_generation,
		skey_revocation_state &	storage_key_state )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Complete storage-key revocation after required translation invalidation is done.

Parameters

[in]	state	Isolation state whose storage key can be returned to DGP policy.
[in,out]	storage_key	The domain's hardware storage key.
[in,out]	storage_key_generation	Storage key generation counter.
[in,out]	storage_key_state	Storage key revocation state.

Returns: Success when DGP-owned key metadata is no longer reusable by stale mappings.

Note: The key generation is advanced by the storage-key allocator when the key is released.

Warning: Callers must only invoke this after VM, DAT, and portal teardown have completed.

Parameters

[in]	state	Isolation state whose storage key can be returned to DGP policy.
[in,out]	storage_key	The domain's hardware storage key.
[in,out]	storage_key_generation	Storage key generation counter.
[in,out]	storage_key_state	Storage key revocation state.

Returns: Success when DGP-owned key metadata is no longer reusable by stale mappings.

◆ create_domain()

auto zxfoundation::dgp::isolation::create_domain	(	u32	domain_id,
		const isolation_policy &	policy )->std::expected< isolation_domain_state, lib::kernel_error >

nodiscardexportnoexcept

Create initial DGP isolation state for a domain.

Parameters

[in]	domain_id	Domain identifier assigned by the caller.
[in]	policy	Hardware-first isolation policy for the domain.

Returns: Isolation domain state, or a kernel error.

Note: This skeleton allocates storage-key ownership and records policy state; later wiring supplies committed ASCE roots from the MMU/domain transaction.

Warning: On success, callers must either activate or destroy the returned state to avoid leaking storage-key ownership.

Parameters

[in]	domain_id	Domain identifier assigned by the caller.
[in]	policy	Hardware-first isolation policy for the domain.

Returns: Isolation domain state, or a kernel error.

◆ destroy_domain()

auto zxfoundation::dgp::isolation::destroy_domain	(	lifecycle_state &	state,
		u8 &	storage_key,
		u32 &	storage_key_generation,
		skey_revocation_state &	storage_key_state,
		std::atomic< u16 > &	revocation_epoch )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Destroy DGP isolation state for a domain.

Parameters

[in]	state	Domain lifecycle state.
[in,out]	storage_key	The domain's hardware storage key.
[in,out]	storage_key_generation	Storage key generation counter.
[in,out]	storage_key_state	Storage key revocation state.
[in,out]	revocation_epoch	Revocation epoch counter.

Returns: Success when storage-key ownership is released; SCOMS records the terminal state.

Note: This helper releases DGP-owned identity only; the caller remains responsible for DAT tables, VM regions, portals, gates, and stacks.

Warning: Destruction with active gate or portal counts is rejected to prevent stale authority use.

Parameters

[in]	state	Domain lifecycle state.
[in,out]	storage_key	The domain's hardware storage key.
[in,out]	storage_key_generation	Storage key generation counter.
[in,out]	storage_key_state	Storage key revocation state.
[in,out]	revocation_epoch	Revocation epoch counter.

Returns: Success when storage-key ownership is released; SCOMS records the terminal state.

◆ init()

auto zxfoundation::dgp::isolation::init ( ) ->void

exportnoexcept

Initialize the DGP isolation clean core.

Note: The initial implementation resets the bootstrap storage-key registry before domain-visible DGP objects exist.

Warning: This function must run before domain, gate, or portal policy is exposed to user-visible objects.

◆ revoke_domain_rights()

auto zxfoundation::dgp::isolation::revoke_domain_rights	(	zxfoundation::dgp::domain::domain &	d,
		dgp::isolation::isolation_rights	drop_mask )->std::expected< void, lib::kernel_error >

exportnoexcept

Lazy revocation of DGP rights on a domain.

Parameters

[in]	d	Target domain. Must be non-null and active.
[in]	drop_mask	Bits to clear from `granted_rights`. Bits not currently set have no effect.

Returns: Success on completion, or kernel_error when d is not active.

Parameters

[in]	d	Target domain. Must be non-null and active.
[in]	drop_mask	Bits to clear from `granted_rights`.

Returns: Success on completion, or kernel_error when d is not active.

◆ validate_gate_entry()

auto zxfoundation::dgp::isolation::validate_gate_entry	(	u32	caller_domain_id,
		u32	gate_id,
		dgp::isolation::isolation_rights	requested )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate entry into a DGP gate chokepoint (structural validation only).

Parameters

[in]	caller_domain_id	Domain requesting entry.
[in]	gate_id	Gate identifier being entered.
[in]	requested	Rights required by the gate operation.

Returns: Success when the request is structurally valid.

Note: Full gate validation (existence, state, rights) is performed by dispatch::validate_call.

◆ validate_portal()

auto zxfoundation::dgp::isolation::validate_portal	(	u32	source_domain_id,
		u32	target_domain_id,
		u64	va_start,
		u64	va_end,
		dgp::isolation::isolation_rights	requested )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate creation or use of a DGP portal.

Parameters

[in]	source_domain_id	Domain that will hold the portal authority.
[in]	target_domain_id	Domain whose address space is exposed through the portal.
[in]	va_start	First target virtual address exposed through the portal.
[in]	va_end	Exclusive end of the target virtual range.
[in]	requested	Rights requested for the portal mapping.

Returns: Success when the portal request is structurally valid.

Note: Later migration binds this validation to ASTE/ALE ownership, ALB invalidation, and capability policy.

Warning: This function does not allocate an ASTE, create an ALE, or install access-register state.

Parameters

[in]	source_domain_id	Domain that will hold the portal authority.
[in]	target_domain_id	Domain whose address space is exposed through the portal.
[in]	va_start	First target virtual address exposed through the portal.
[in]	va_end	Exclusive end of the target virtual range.
[in]	requested	Rights requested for the portal mapping.

Returns: Success when the portal request is structurally valid.

◆ validate_scheduler_admission()

auto zxfoundation::dgp::isolation::validate_scheduler_admission	(	const lifecycle_state	state,
		u64	root_phys,
		u64	asce_raw )->std::expected< void, lib::kernel_error >

nodiscardexportnoexcept

Validate that a DGP domain may be admitted to a CPU run queue.

Parameters

[in]	state	Isolation state associated with the candidate domain.
[in]	root_phys	Physical address of the region-first root table.
[in]	asce_raw	Raw ASCE value.

Returns: Success when the domain is active and has committed ASCE metadata.

Note: Scheduler admission is a hardware boundary because a later context switch may load the ASCE into CR1.

Warning: Callers must still serialize run-queue mutation with the scheduler lock after this check succeeds.

Parameters

[in]	state	Isolation state associated with the candidate domain.
[in]	root_phys	Physical address of the region-first root table.
[in]	asce_raw	Raw ASCE value.

Returns: Success when the domain is active and has committed ASCE metadata.

◆ validate_scheduler_policy()

auto zxfoundation::dgp::isolation::validate_scheduler_policy	(	const lifecycle_state	state,
		const zxfoundation::sched::sched_policy &	policy,
		bool	has_rt_authority )->std::expected< zxfoundation::sched::sched_admission_result, lib::kernel_error >

nodiscardexportnoexcept

Validate a scheduler policy against DGP authority and basic safety invariants.

Parameters

[in]	state	Domain isolation state requesting scheduler admission.
[in]	policy	Requested scheduler policy.
[in]	has_rt_authority	True when the caller holds the domain's RT/admin capability authority.

Returns: Scheduler admission result, or kernel_error describing the denied request.

Note: RT and deadline bandwidth reservation is completed by scheduler backends after this DGP check.

Warning: User-visible RT requests must pass this function before any run-queue insertion.

Parameters

[in]	state	Domain isolation state requesting scheduler admission.
[in]	policy	Requested scheduler policy.
[in]	has_rt_authority	True when the caller holds the domain's RT/admin capability authority.

Returns: Scheduler admission result, or kernel_error describing the denied request.

ZXFoundation™ 26h2

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ lifecycle_state

Function Documentation

◆ activate_domain()

◆ begin_portal_teardown()

◆ begin_storage_key_revocation()

◆ bind_asce_root()

◆ complete_storage_key_revocation()

◆ create_domain()

◆ destroy_domain()

◆ init()

◆ revoke_domain_rights()

◆ validate_gate_entry()

◆ validate_portal()

◆ validate_scheduler_admission()

◆ validate_scheduler_policy()