Skip to content
Linux Systems Field Manual

Rust Translation

Imported from _research/manual-study-linux/rust-translation.md.

Rust Translation Guide

This document captures Linux implementation lessons that can shape a Rust-first operating system or runtime. Every claim should point back to a source note once the related file is reviewed.

Translation Rules

  • Prefer Rust ownership and lifetime boundaries over direct C pattern copying.
  • Translate operation tables into traits only when dynamic dispatch is actually part of the model.
  • Keep unsafe boundaries narrow, named, and documented.
  • Treat Linux locking and RCU patterns as concurrency contracts before choosing Rust primitives.
  • Preserve subsystem separations even if Rust modules make tighter coupling convenient.

Initial Translation Questions

  • Which Linux objects map to Arc, owned handles, borrowed guards, or arenas?
  • Which Linux operation tables should become traits, enums, or explicit command dispatch?
  • Where does a Rust kernel need pinning, intrusive collections, or custom allocators?
  • Which C global registries should become typed registries with capability checks?
  • How should async/deferred work interact with scheduler and interrupt boundaries?

Pending Track Notes

Kernel API Boundary

Use a single Rust kernel/runtime crate as the membrane around raw platform bindings. New low-level capabilities should enter through audited wrappers, not direct FFI calls from product subsystems.

Evidence: file-notes/linux__rust__kernel__lib.rs.md.

Initialization Typestates

Keep ordinary initialization separate from pinned in-place initialization. For kernel objects, model states such as uninitialized allocation, unique initialized object, pinned unique object, and shared pinned object as distinct types where practical.

Evidence: file-notes/linux__rust__kernel__lib.rs.md, file-notes/linux__rust__kernel__sync__arc.rs.md.

Ownership Handle Set

A Rust kernel needs at least three ownership surfaces for shared objects: shared pinned ownership, borrowed refcount-capable access, and unique pre-publication ownership. Arc, ArcBorrow, and UniqueArc provide the pattern.

Evidence: file-notes/linux__rust__kernel__sync__arc.rs.md.

Context-Sensitive Task APIs

Separate ambient/current task access from durable task references. A CurrentTask-style type should be non-thread-safe and scoped to the active task context, while durable handles should explicitly hold a reference.

Evidence: file-notes/linux__rust__kernel__task.rs.md.

Process Creation Builder

Translate copy_process into a staged Rust builder with RAII cleanup guards and explicit commit points. Avoid a direct line-by-line port of the C function; preserve the staged validation/copy/publish/wake lifecycle.

Evidence: file-notes/linux__kernel__fork.c.md.

Typed Runqueue Guards

Model per-CPU runqueues as typed objects whose access requires a lock guard. The guard should encode whether the runqueue is locked, pinned, and operating with interrupts/preemption disabled. Scheduler methods should accept the guard type they require instead of relying on comments.

Evidence: file-notes/linux__kernel__sched__sched.h.md, file-notes/linux__kernel__sched__core.c.md.

Scheduler Class Traits

Translate struct sched_class into a sealed trait or static vtable only where runtime class dispatch is needed. The trait surface should preserve Linux’s events: enqueue, dequeue, wakeup preemption, balance, pick, put previous, set next, CPU selection, migration, tick, fork, death, and class-change hooks.

Evidence: file-notes/linux__kernel__sched__sched.h.md, file-notes/linux__Documentation__scheduler__sched-design-CFS.rst.md.

Fair Scheduler Data Structures

A Rust fair scheduler needs scheduling entities with virtual runtime, lag, deadline, and slice state. EEVDF requires an ordered/augmented queue; use an arena-backed or intrusive tree deliberately rather than ordinary collections that hide lifetime and pointer stability costs.

Evidence: file-notes/linux__kernel__sched__fair.c.md, file-notes/linux__Documentation__scheduler__sched-eevdf.rst.md.

RT And Deadline Admission Types

Static-priority RT scheduling should pair priority queues with explicit runtime budget state. Deadline scheduling should construct validated reservation types where runtime, deadline, and period invariants are checked before admission. Throttled and replenishment states should be part of the entity model.

Evidence: file-notes/linux__kernel__sched__rt.c.md, file-notes/linux__kernel__sched__deadline.c.md, file-notes/linux__Documentation__scheduler__sched-rt-group.rst.md, file-notes/linux__Documentation__scheduler__sched-deadline.rst.md.

Context Switch Unsafe Boundary

Keep the architecture register/stack switch as a narrow unsafe boundary. The surrounding phases should remain typed and auditable: pre-switch accounting, memory-map switching, barrier obligations, lock handoff, post-switch cleanup, and dead-task reference release.

Evidence: file-notes/linux__kernel__sched__core.c.md.

Address Space And VMA Types

Translate Linux memory state into separate Rust types: AddressSpace, Vma, FaultContext, FaultResult, PageTableWalker, and PteLocked. VMA flags should be opaque bitflags with controlled mutation APIs. A fault handler should not be able to mutate page tables unless it holds the typed page-table lock guard.

Evidence: file-notes/linux__include__linux__mm_types.h.md, file-notes/linux__include__linux__mm.h.md.

Fault Handling State Machine

The fault path should be a state machine rather than a monolithic unsafe function. States should encode VMA locked, page-table level allocated, PTE locked, folio locked, COW page allocated, and PTE installed. Retry and drop-lock outcomes must invalidate borrowed VMA handles.

Evidence: file-notes/linux__mm__memory.c.md.

Typed Slab Caches

Use validated SlabCache<T> handles for repeated kernel objects. Creation should encode size, alignment, accounting, usercopy region, merge policy, and RCU teardown behavior. Destruction should require proof that no live objects remain or be explicitly unsafe.

Evidence: file-notes/linux__mm__slab_common.c.md, file-notes/linux__Documentation__core-api__memory-allocation.rst.md.

AI Contribution Metadata

Treat AI provenance as structured metadata separate from human certification. Do not let tool-generated changes forge human sign-off.

Evidence: file-notes/linux__Documentation__process__coding-assistants.rst.md.