Module n3 

N3 MMU Thread Migration : PCID-preserving (N3b) and Full Isolation (N3c).

Implements the transport layer for IPC level N3

Architecture

sender ──send()──▶ MigrationFrame ──CR3 switch──▶ receiver handler
  ▲                                                    │
  └────────────── reschedule IPI ◀─────────────────────┘

The sender saves its context, copies the message, then calls the ASM primitive which switches CR3 and restores the receiver’s context. The receiver handler reads the message from the frame and returns. The sender is resumed via a reschedule IPI.

Frame pointer requirement

The send() method captures sender_rip from [rbp + 8], which requires frame pointers to be enabled at compile time. The kernel must be built with -C force-frame-pointers=yes (see workspace/kernel/.cargo/config.toml).

Shared mapping note

The MigrationFrame is mapped in both address spaces at the same virtual address (N3_SHARED_FRAME_VA), but without USER_ACCESSIBLE. The frame lives in kernel space and is accessible only from Ring 0. Both sender and receiver access it via their kernel page tables : the shared VA means the same PTE (same physical page) is reachable from both page table hierarchies. This is NOT a user-mappable region; it is kernel-only shared memory.

PCID contract

A PCID value of 0 means “no PCID” : either PCID is unsupported by the CPU or exhausted. All code paths check pcid > 0 before using PCID-specific features (INVPCID, CR3 PCID bits). The tier selection function (select_n3_tier()) distinguishes theoretical CPU support from actual operational capability.

Structs

FrameAllocator 🔒

Bitmap-based O(1) frame allocator.

FramePool 🔒

Static pool of MigrationFrame slots.

MigrationFlags

Flags for a migration operation.

MigrationFrame

Shared migration frame : one per N3 transport endpoint pair.

MsgBuffer 🔒

Wrapper for a raw pointer to the shared message buffer.

N3MinimalContext

Minimal CPU context saved/restored during N3 migration.

N3Transport

N3 MMU transport : thread migration between distinct address spaces.

WatchdogEntry 🔒

Watchdog state per frame.

Enums

MigrationState

Migration state machine.

N3Tier

N3 tier selection

Constants

MAX_PCIDS 🔒

Maximum number of PCIDs before panic (x86-64 supports 4096).

N3_FRAME_POOL_SIZE 🔒

Number of pre-allocated migration frames.

N3_HANDLER_STACK_SIZE 🔒

Size of the per-N3Transport handler stack (1 page). After CR3 switch, the ASM primitive loads RSP from dst_ctx.rsp which points to this stack with the handler address as the return address.

N3_MSG_BUF_SIZE

Maximum message size for N3 transport (separate buffer, not in frame).

N3_SHARED_FRAME_VA

Virtual address where the MigrationFrame is mapped in both address spaces. Located in canonical upper-half, just below the HHDM boundary.

N3_SHARED_MSG_BUF_VA

Virtual address where the shared message buffer is mapped. Must be distinct from N3_SHARED_FRAME_VA to avoid page table conflicts.

N3_WATCHDOG_TIMEOUT 🔒

Default watchdog timeout in TSC cycles (~10ms at 3GHz).

Statics

N3_FRAME_ALLOC 🔒

N3_FRAME_POOL 🔒

N3_PENDING_MIGRATION 🔒

Per-CPU pending migration frame pointer. Set by the sender before sending the IPI, consumed by the IPI handler.

N3_WATCHDOG_TABLE 🔒

Global watchdog table.

PCID_COUNTER 🔒

Global PCID counter : monotonic allocation, panics at 4096 (prototype).

Functions

alloc_frame_slot 🔒

Allocate a MigrationFrame from the static pool.

allocate_pcid

Allocate a stable PCID for an address space.

frame_pool_phys_addr 🔒

Get the physical address of a frame in the static pool.

free_frame_slot 🔒

Free a MigrationFrame back to the pool.

free_pcid

Free a PCID back to the pool (called when an address space is destroyed).

map_frame_in_both_spaces 🔒

Map a MigrationFrame’s physical page into both sender and receiver address spaces at N3_SHARED_FRAME_VA.

map_msg_buf_in_both_spaces 🔒

Map a message buffer’s physical page into both address spaces at N3_SHARED_MSG_BUF_VA.

map_page_in_space 🔒

Map a physical page into an address space at the specified virtual address.

n3_frame_generation

Get the current generation counter of a frame.

n3_frame_is_ready

Check if a frame is in the Ready state.

n3_frame_state

Get the current migration state of a frame.

n3_migrate_ipi_entry^⚠

Naked IPI handler for N3 migration synchronization.

n3_migrate_ipi_handler

Fallback handler for N3 migration IPI (non-naked path).

n3_prepare_migration 🔒

Prepare a MigrationFrame for a send operation.

n3_watchdog_tick

Called from the timer ISR to check for stalled migrations.

n3b_migrate_asm^⚠

ASM migration primitive.

pcid_available

Check if PCID feature is available on this CPU.

safe_kernel_rflags 🔒

Return safe kernel-mode rflags for N3 context switching.

select_n3_tier

Select the N3 tier based on actual PCID capability.

send_n3_sync_ipi 🔒

Send a migration-sync IPI to the target CPU.

shared_msg_read 🔒

Read the message payload from a shared message buffer.

shared_msg_write 🔒

Write a message payload into a shared message buffer.

unmap_from_both_spaces 🔒

Unmap the MigrationFrame and message buffer from both address spaces.

unmap_page_in_space 🔒

Unmap a single page from an address space and shoot down TLB on all CPUs.

validate_rip 🔒

Validate that rip points to an authorized executable page.

walk_page_tables_executable 🔒 ^⚠

Walk x86-64 4-level page tables to check if vaddr is present, executable, and supervisor-only (U/S=0).

watchdog_recover 🔒

Recover a stalled frame : reset to Ready via atomic CAS transitions.

watchdog_register 🔒

Register a frame with the watchdog.

watchdog_unregister 🔒

Unregister a frame from the watchdog.