Rust in the Linux Kernel
Relevant source files
The following files were used as context for generating this wiki page:
The Rust in the Linux Kernel project integrates the Rust programming language into the Linux kernel to provide a safer alternative for system-level development. It enables the creation of kernel modules and drivers using Rust's memory safety guarantees while interfacing with existing C-based kernel infrastructure.
This integration includes a dedicated toolchain, a set of coding guidelines, and abstraction layers that wrap C kernel functionality. Developers use these tools to write "Leaf" modules, such as drivers, while avoiding direct use of raw C bindings where safe abstractions are available.
Sources: Documentation/rust/index.rst:5-7, Documentation/translations/zh_CN/rust/general-information.rst:11-14, Documentation/translations/zh_CN/rust/general-information.rst:40-45
Toolchain and Requirements
Building Rust code within the kernel requires specific tools and environment configurations. The build system supports a complete LLVM toolchain for the best experience.
Component Requirements
To compile Rust code, you must install the following components:
- rustc: A recent version of the Rust compiler.
- Rust standard library source: Required because the build system cross-compiles the
corecrate. - libclang: Part of LLVM, used by
bindgento parse C headers. - bindgen: A tool that generates Rust declarations for C functions and types at build time.
Sources: Documentation/rust/quick-start.rst:133-210, Documentation/rust/quick-start.rst:294-297
Development Tools
For active development, the project utilizes several additional tools:
- rustfmt: Automatically formats code to follow idiomatic Rust styles and kernel-specific import layouts.
- clippy: A linter that provides extra warnings and analysis.
- rust-analyzer: A language server for IDE features like syntax highlighting and completion.
Sources: Documentation/rust/quick-start.rst:225-274, Documentation/rust/coding-guidelines.rst:14-18
Build Process Flow
The following diagram illustrates how the Rust toolchain interacts with the C kernel source to produce the final build.
The diagram shows the dependency of rustc on generated C bindings and the Rust standard library to produce kernel objects.
Sources: Documentation/rust/quick-start.rst:133-210, Documentation/translations/zh_CN/rust/general-information.rst:33-38
Coding Guidelines
Rust code in the kernel must adhere to specific style and safety requirements to ensure maintainability and soundness.
Style and Formatting
- Indentation: Use 4 spaces rather than tabs.
- Imports: Use a vertical layout where each item occupies its own line, and braces are used for multiple items. A trailing empty comment
//is often used to force this vertical formatting inrustfmt. - Comments: Use Markdown syntax for all comments. Capitalize the first letter and end with a period.
Sources: Documentation/rust/coding-guidelines.rst:22-26, Documentation/rust/coding-guidelines.rst:45-55, Documentation/rust/coding-guidelines.rst:111-115
Safety and Documentation
Safety documentation is mandatory for unsafe code. The kernel distinguishes between the requirements for callers and the proof of implementation.
| Feature | Syntax | Purpose |
|---|---|---|
| Safety Preconditions | # Safety section in /// docs | Specifies the contract callers or trait implementors must follow. |
| Safety Proof | // SAFETY: comment | Explains why an unsafe block or implementation is sound. |
| Panic Documentation | # Panics section in /// docs | Describes conditions under which a function might panic. |
| Examples | # Examples section in /// docs | Demonstrates usage to readers. |
Sources: Documentation/rust/coding-guidelines.rst:155-165, Documentation/rust/coding-guidelines.rst:180-195
Architecture and Abstractions
The project uses a layered architecture to bridge Rust safety with C efficiency.
Bindings vs. Abstractions
- Bindings: These are direct Rust declarations of C functions and types, usually generated by
bindgen. - Abstractions: These are Rust-native wrappers (e.g., a
Mutexstruct) that encapsulate C functionality to provide a safe API. Subsystems provide these to ensure "Leaf" modules do not need to call unsafe C functions directly.
Sources: Documentation/translations/zh_CN/rust/general-information.rst:33-45
Conditional Compilation
Rust code uses the #[cfg(...)] attribute to handle kernel configuration options defined in Kconfig.
#[cfg(CONFIG_X)] // Enabled (y or m)
#[cfg(CONFIG_X="y")] // Enabled as built-in
#[cfg(not(CONFIG_X))] // Disabled
Sources: Documentation/translations/zh_CN/rust/general-information.rst:54-58
Error Handling
The kernel uses a specialized Result type that maps Rust's error handling to C's integer-based error codes. Panicking is discouraged; fallible functions should return a Result.
Sources: Documentation/rust/coding-guidelines.rst:186-189, Documentation/rust/coding-guidelines.rst:403-406
Integration and Contribution
Integrating Rust into the kernel involves both build system changes and adherence to established community processes.
Kernel Configuration
Rust support is enabled via CONFIG_RUST in the "General setup" menu. This option only appears if the environment meets all toolchain requirements.
Sources: Documentation/rust/quick-start.rst:280-285
Commit Requirements
For contributions to foundational crates like pin-init, the following rules apply:
- Logical Cohesion: Each commit must be a single, logically cohesive change.
- Bisection: The code must compile without errors or warnings after every single commit.
- DCO: All commits must include a
Signed-off-bytag following the Developer's Certificate of Origin. - Prefixing: Changes to internal directories should be prefixed (e.g.,
internal: title).
Sources: rust/pin-init/CONTRIBUTING.md:37-52
Rust in the Linux Kernel provides the infrastructure to improve memory safety in the kernel while maintaining performance and compatibility with existing C subsystems through formal abstractions and a strict toolchain.