Rust support

Purpose

rust/ is the Rust support layer of the kernel. It provides a kernel crate with safe (or carefully-typed unsafe) wrappers around core kernel primitives, the C-to-Rust bindings (via bindgen), and the build glue needed to compile Rust files alongside C in Kbuild.

Rust support landed in 6.1 (December 2022) and has been growing every release. As of 7.1-rc1 it is opt-in (CONFIG_RUST=y) and not yet on the critical path of any major subsystem, but several drivers and abstractions are present.

Directory layout

rust/
├── Makefile, build_error.rs, exports.c, ffi.rs, compiler_builtins.rs
├── bindings/             # Auto-generated bindings to C kernel headers
├── helpers/              # Hand-written C helpers exposing inline-defined kernel APIs to Rust
├── kernel/               # The `kernel` crate: safe abstractions
│   ├── lib.rs            # Crate root
│   ├── alloc.rs          # Allocator integration with kmalloc / vmalloc
│   ├── error.rs          # Result / Error types
│   ├── sync/             # Mutex, RWlock, Arc, etc.
│   ├── workqueue.rs, time.rs, str.rs, types.rs
│   ├── init.rs, init/    # Pin-init machinery
│   ├── task.rs, sched.rs, miscdevice.rs, chrdev.rs
│   ├── net/, fs/, dma.rs, devres.rs, of.rs, platform.rs, pci.rs, irq.rs
│   ├── print.rs          # pr_info!, pr_err! macros
│   └── ...
├── macros/               # Procedural macros (e.g. `module!`, `vtable!`)
├── pin-init/             # Pinned-initializer machinery (for self-referential structs)
├── proc-macro2/, quote/, syn/   # Vendored proc-macro support crates
├── uapi/                 # User-space-facing types (mirroring `include/uapi`)
└── bindgen_parameters    # Build flags for bindgen

Key abstractions

Symbol	File	Purpose
kernel::Result<T>	rust/kernel/error.rs	Wrapper around Result<T, Error> with errno conversion.
kernel::sync::Mutex<T>	rust/kernel/sync/lock/mutex.rs	Safe wrapper over struct mutex.
kernel::sync::Arc<T>, UniqueArc<T>	rust/kernel/sync/arc.rs	Refcounted pointers using refcount_t.
module! macro	rust/macros/lib.rs	Declares a kernel module entirely in Rust.
pin_init!, try_pin_init!	rust/kernel/init.rs	The pin-init pattern: in-place construction in pinned memory.
bindings::*	rust/bindings/	Direct, unsafe C-binding types.
pr_info!, pr_err!, etc.	rust/kernel/print.rs	Logging macros.

How it works

graph LR
    HEADERS[include/linux/*.h] -->|bindgen| BIND[rust/bindings/]
    HELPERS[rust/helpers/*.c] -->|exposes inlines| BIND
    BIND -->|raw FFI| KERNEL_CRATE[rust/kernel/ — the safe `kernel` crate]
    KERNEL_CRATE --> DRIVER[Driver in Rust]
    DRIVER -->|"`module!` macro"| KO[Compiled module .ko]
    DRIVER -->|init/exit| RUNTIME[Rust runtime: alloc, panic_handler]
    RUNTIME --> ALLOC[rust/kernel/alloc.rs → kmalloc]

Bindings

bindgen generates Rust types and FFI prototypes from kernel C headers. Output goes to rust/bindings/. Inline functions don't survive bindgen, so rust/helpers/ provides hand-written C wrappers that the Rust side can call.

The kernel crate

rust/kernel/ is the safe surface. It wraps unsafe C operations behind types that uphold the kernel's invariants: Mutex<T> doesn't let you forget to unlock, Arc<T> uses the kernel's refcount_t, Box::new_in(...) allocates from a kernel-aware allocator that returns Result on failure (no panic on OOM). Drivers should use this crate, not raw bindings.

Pin-init

A core pattern: many kernel structs are self-referential or contain types that can't be moved (struct mutex, struct list_head). Rust's safe move semantics conflict. rust/pin-init/ and rust/kernel/init.rs provide the pin_init! / try_pin_init! macros that initialize objects in place behind a Pin<&mut T>.

let m: KBox<Mutex<u32>> = KBox::pin_init(new_mutex!(42, "my-mutex"), GFP_KERNEL)?;

module! macro

Defines a kernel module in Rust. Generates the module_init / module_exit glue, the parameter declarations, the license string, and the Rust runtime.

module! {
    type: MyModule,
    name: "my_module",
    author: "...",
    license: "GPL v2",
}

Allocation

Heap allocation is kmalloc-backed. The crate provides KVec<T>, KBox<T>, KString wrappers with explicit GFP flags. There is no implicit GlobalAlloc-style global allocator, so allocation always declares its context.

Drivers and abstractions in tree

A growing list. As of 7.1-rc1, Rust abstractions exist for (or are being upstreamed for) miscdev, chrdev, pci, platform, of (devicetree), irq, dma, devres, workqueue, str, time, sched, task, fs, net, miscdevice. A small number of working drivers using these wrappers ship in samples/rust/ and elsewhere. The detailed list moves quickly; check git log -- rust/ for the current state.

Integration points

• scripts/Makefile.build and scripts/Makefile.lib — Kbuild knows how to compile .rs files, run bindgen, and link the resulting object code.
• kernel/printk/: Rust pr_* macros call into printk.
• mm/: KBox/KVec call kmalloc/krealloc.
• kernel/locking/: Mutex/RwLock wrap kernel mutex/rwsem.
• drivers/base/: device, devres, platform, pci abstractions wrap the device model.

Build requirements

• A specific Rust version (currently >= 1.78.0; check Documentation/rust/quick-start.rst for the exact requirement).
• bindgen, rustfmt, clippy (also pinned versions).
• Either Clang+LLD or GCC. With Clang, LLVM=1 is required.

rustup toolchain install nightly
make LLVM=1 rustavailable     # tells you what's missing
make LLVM=1 menuconfig        # turn on CONFIG_RUST and a Rust sample
make LLVM=1 -j$(nproc)

Key source files

File	Purpose
rust/kernel/lib.rs	Crate root, top-level docs.
rust/kernel/error.rs	Result<T> and Error.
rust/kernel/sync/lock/mutex.rs	Mutex wrapper.
rust/kernel/sync/arc.rs	Arc over refcount_t.
rust/kernel/init.rs	Pin-init machinery.
rust/macros/lib.rs	module! and other procedural macros.
rust/Makefile	Build glue.
rust/exports.c	Symbol exports.

Entry points for modification

• New abstraction: add a module to rust/kernel/. Read recent Rust patches and discussions on rust-for-linux@vger.kernel.org.
• New driver in Rust: typically in drivers/<bus>/<vendor>_rust.rs or similar. Coordinate with the subsystem maintainer; many subsystems prefer to take Rust drivers only after the corresponding abstractions are in place.
• Updating the toolchain version: changes Documentation/process/changes.rst and Documentation/rust/.

Related pages

• Tooling — Kbuild integration.
• Drivers — where Rust drivers live.
• Kernel core — the C primitives that Rust wraps.
• Memory management — kmalloc/kvmalloc backing.