Skip to content
Linux Systems Field Manual

linux/rust/kernel/lib.rs

Imported from _research/manual-study-linux/file-notes/linux__rust__kernel__lib.rs.md.

File Notes: rust/kernel/lib.rs

Status: reviewed.

Purpose

rust/kernel/lib.rs is the root crate surface for Rust code inside the Linux kernel. It explicitly presents Rust as a wrapped kernel API layer: Rust modules depend on core and this crate, and missing C APIs should be wrapped here rather than bypassed directly.

Key Types And Functions

  • #![no_std] makes the crate independent of Rust’s standard library.
  • Conditional Rust features are declared at the crate root.
  • #[cfg(not(CONFIG_RUST))] compile_error!(...) prevents silent builds without kernel Rust configuration.
  • Public modules expose subsystem wrappers such as alloc, device, fs, mm, sync, task, workqueue, and xarray.
  • Module models normal module initialization.
  • InPlaceModule models pinned in-place initialization.
  • ThisModule wraps the C THIS_MODULE pointer.

Data Flow

Rust kernel users enter through this crate rather than calling arbitrary C interfaces. The root crate re-exports generated bindings, macros, and uapi, but the file’s own docs direct developers to port or wrap C APIs in this crate first. Module initialization flows through Module::init, then the blanket InPlaceModule implementation adapts normal initialization into a pin-init closure.

Invariants And Safety Contracts

  • Rust support is tied to kernel configuration; the crate errors when CONFIG_RUST is unavailable.
  • ThisModule::from_ptr is unsafe because callers must pass the correct module pointer.
  • ThisModule is marked Sync because the kernel module pointer may be used from all threads within a module.
  • Module setup is pinned through InPlaceModule when in-place initialization is required.

Rust Translation Guidance

A Rust-first Linux-like system should copy the boundary idea, not the exact module list: define a single kernel/runtime crate that owns all unsafe platform bindings and exposes typed safe wrappers. Do not let feature teams call raw FFI everywhere. The root crate should make unsupported configuration states fail loudly, and subsystem APIs should be feature-gated at the crate boundary.

The Module / InPlaceModule split is an important design pattern: provide a simple initialization trait for ordinary cases, but keep a pin-init path for objects that must never move after construction.

AI-Native Systems Guidance

AI agents need an explicit API membrane like this crate. The agent should be able to reason over stable subsystem wrappers, not ad hoc FFI calls. The root crate also suggests a policy pattern: agents should add new low-level capabilities by introducing audited wrappers, then consume those wrappers in higher-level work.

Evidence

  • rust/kernel/lib.rs:3-12: crate purpose and rule to wrap missing C APIs here.
  • rust/kernel/lib.rs:14-31: no_std and unstable/conditional feature setup.
  • rust/kernel/lib.rs:33-39: configuration guard and crate self-alias.
  • rust/kernel/lib.rs:43-138: public subsystem module surface.
  • rust/kernel/lib.rs:148-181: module and in-place initialization traits.
  • rust/kernel/lib.rs:184-214: module metadata and ThisModule wrapper.