Crate cpu_local 

cpu-local

Typed ownership boundary for CPU-local architecture registers.

The crate owns the fixed CpuAreaPrefix, CPU binding/epoch validation, current-thread publication, and task-pointer register operations. It does not allocate CPU areas, define per-CPU variables, schedule tasks, or choose IRQ policy; those responsibilities remain in ax-percpu, platform boot code, and the scheduler.

Architecture	CPU area	Current thread	TLS
x86_64	GS base	GS runtime anchor	FS base
AArch64	TPIDR_EL1/EL2	SP_EL0	TPIDR_EL0
RISC-V	prefix recovery or sscratch	tp=current, sscratch=0	tp=TLS, sscratch=CPU base
LoongArch64	r21, mirrored in KS3	tp=current	tp=TLS

LoongArch KS4 and KS5 are deliberately outside this contract and remain available to vCPU scratch state.

The tls feature selects the TLS-owning image mode; without it the current thread occupies the architecture task-pointer register. host-test provides a thread-local register model for host-side tests. These are the crate’s only features; no runtime mode enum or ABI version is retained inside one final image.

Scheduler publication follows a strict sequence: validate the pinned binding, bind the next task header, prepare all fallible architecture work, consume a PreparedThreadSwitch to publish the next header immediately before the raw switch, then consume PreviousThreadBinding in the incoming tail. Dropping an uncommitted prepared token rolls the next binding back. The binding epoch is a runtime stale-tail guard, not an ABI version.

CpuPin can only be created by the higher-ranked with_cpu_pin boundary and cannot escape its migration guard. ExclusiveCpu additionally represents excluded local IRQ/re-entry and conflicting remote access. This crate validates those capabilities but does not itself disable preemption or interrupts.

The exact initialized CpuAreaRef address is the layout identity. There is no ABI version, generation, or cookie inside one final image. The task binding epoch is intentionally retained because it rejects an obsolete incoming switch tail after the same task has been rebound.

Operation	Required protection
Atomic per-CPU scalar	Migration disabled; local IRQs may remain enabled
Shared T: Sync object	Migration disabled; object-owned synchronization
Local mutable object	Migration, IRQ/re-entry, and remote conflicts excluded
Scheduler switch	IRQs and migration disabled; prepared/previous tokens consumed
vCPU execution	Migration disabled; host registers restored before host Rust
CPU-area installation	CPU offline, traps disabled, area exclusively owned

Licensed under Apache-2.0.

Structs

BootThreadHeader

Permanent current header used before the scheduler publishes a task.

CpuAreaHeader

Immutable identity stored at the beginning of each initialized CPU area.

CpuAreaPrefix

Fixed three-cache-line prefix of every initialized runtime CPU area.

CpuAreaRef

Permanent typed reference to one fully initialized runtime CPU area.

CpuIndex

Dense logical index assigned to one CPU-local area.

CpuIndexError

Error returned when a logical CPU index does not fit the supported range.

CpuPin

Scoped proof that execution cannot migrate away from one validated CPU.

CpuRuntimeAnchor

CPU-local scalar state shared by trap entry and scheduler publication.

CurrentContext

Stable opaque identity of one runtime-owned execution context.

CurrentThreadHeader

Pinned scheduler/architecture header for one execution context.

ExclusiveCpu

Scoped proof of exclusive local access to CPU-owned mutable state.

PreparedThreadSwitch

Prepared current-thread publication owned by the final context-switch tail.

PreviousThreadBinding

Opaque previous-task binding consumed by the incoming switch tail.

Enums

CpuLocalError

Failure to construct, install, or observe CPU-local state.

ThreadSwitchError

Failure while preparing or completing a scheduler thread switch.

Constants

CPU_AREA_ARCH_STATE_OFFSET

Byte offset of architecture-owned CPU trap state.

CPU_AREA_ARCH_STATE_SIZE

Reserved bytes available to the architecture-owned CPU trap state.

CPU_AREA_BOOT_THREAD_OFFSET

Byte offset of the permanent boot current-thread header.

CPU_AREA_CPU_INDEX_OFFSET

Byte offset of the logical CPU index.

CPU_AREA_CURRENT_THREAD_OFFSET

Byte offset of the current-thread slot.

CPU_AREA_HEADER_SIZE

Size in bytes of the immutable area header.

CPU_AREA_RUNTIME_ANCHOR_OFFSET

Byte offset of CPU runtime/trap state.

CPU_AREA_SELF_BASE_OFFSET

Byte offset of the runtime self pointer.

CURRENT_THREAD_ARCH_STATE_OFFSET

Byte offset of architecture-owned task trap state.

CURRENT_THREAD_ARCH_STATE_SIZE

Reserved bytes available to architecture-owned task trap state.

CURRENT_THREAD_CPU_BASE_OFFSET

Byte offset of the current header’s bound CPU-area base.

Functions

current_thread

Returns the pinned current-thread header after checking both sources.

prepare_thread_switch^⚠

Validates and binds a complete scheduler thread switch transaction.

with_cpu_pin^⚠

Runs operation with a validated, non-escaping CPU pin.

with_exclusive_cpu^⚠

Runs operation with exclusive access to mutable state on the pinned CPU.