a minimal Linux kernel module written in rust

A recent build of Rust (latest nightly)

rust.ko

a minimal Linux kernel module written in rust.

Requirements

  • A recent build of Rust (latest nightly)

This code uses feature flags, so you'll need to use a nightly version of Rust to compile it.

TL;DR

  1. Create a file config.mk in the root directory of the repository.

  2. Set RUST_ROOT in this file to the directory containing bin/rustc, e.g. RUST_ROOT := /usr

  3. Compile rust.ko:

     $ make
    
  4. Try it out:

     # insmod hello.ko
     # rmmod hello
     $ dmesg | tail -3
       [54024.186997] hello: init
       [54024.187000] hello from rust
       [54024.191963] hello: exit
    

make command-line options

Currently there are a few parameters you can pass to make to affect the build:

  • V=1: Enable verbose output
    • All commands run by make and cargo will be printed to the screen
  • RELEASE=1: Create a release build
    • rustc will compile all code in --release mode
    • Debugging information will not be added to the final binary

Notes

Cargo.lock

When running make for the first time cargo will generate a Cargo.lock file in the project's root directory. This file contains information about the exact versions of the dependencies of your project. Since this is an example project it will not ship any Cargo.lock file, but it's recommended that you commit it to your source tree if you're actually trying to build a project based on this code.
(Please don't make any pull requests to this code containing a Cargo.lock file through.)

Build targets

Since Linux code can be compiled for a lot of different architectures, we have to be able to generate CPU code that is in line with what the kernel expects. This means specifically:

  • No floating-point operations in kernel mode at all
  • No CPU instructions that write to floating-point registers (SSE, SMID, … on x86 for instance)
  • No usage of the red zone
  • No target operating system (after all: When you are in kernel mode, you are the operating system)

Currently this source code only ships with a target specification file for the x64_64 architecture. If you get an error similar to the following, you'll have the honor of creating and submitting one for favourite architecture: :wink:

cd "…/rust.ko" && /usr/local/bin/cargo rustc --target="armhf-unknown-none-gnu" --  --emit obj -o "…/rust.ko/build/hello-rust.o"
failed to run `rustc` to learn about target-specific information

Some ideas on how to do this may be found here under the Creating a target file section.

Kernel API and ABI stability

Due to the fact that Linux does not provide any ABI stability (not even for two identical copies of its source code), we must build kernel modules against its API instead. While this is trivially done in C, by building the code against the headers of that kernel version, it's not that easy to do in Rust. Most importantly because Rust cannot read C headers of course, but also because any extern "C" function bindings and, more importantly, any #[repr(C)] structure definitions you define, will link against the kernel's ABI not the API!

Here is an incomplete list of things that affect the kernel's ABI stability:

  • Using a different version of gcc or clang to compile the kernel's source code
  • Adding or removing private fields from kernel data structures (may even happen in minor releases!)
  • Changing kernel build options:
    • Some build options cause data structures to contain extra fields
    • Some functions might just disappear
    • Memory alignment or field ordering might change to make data structures more memory efficient

Check out the kernel documentation for more information on kernel API (in)stability.

Currently rust-bindgen is invoked at the module's build time to generate Rust counterparts for all C data structures, enumerations, functions and types defined by the kernel headers. This addresses most of the issues mentioned above, but is not a silver bullet: No bindings are generated for C macro definitions and in-line functions. Most importantly this matters, because, for a C developer it is often irrelevant whether they declare a bunch of macros for different states of something, or use an enum definition instead; after all, the result is the same, right? While this is certainly true from a C programmers perspective, it is not the same from the compiler's point of view: C macros are expanded during the preprocessor stage, while enums are expanded during the main compiling/assembling stage. For rust-bindgen (that operates on the main compiling stage) this means that all macros have disappeared by the time it gets to look at the source code's AST. There is no way to use C macro definitions because of this at the current time.

Compilation times

The first build will be ratter slow as the kernel header bindings are generated by rust-bindgen. Also, when you target another kernel or change the list of headers used (with the KERNEL_INCLUDE option), you will also experience a delay while the bindings are regenerated.

Please see the Kernel API and ABI stability section for details on why this is necessary for any serious use of the kernel interfaces.

refs

  • rustboot
Issues

Collection of the latest Issues

iakshay

iakshay

0

I'm using linux kernel 4.20.6 and the following clang and rust versions[0]. The make command succeds for me, but I get the following warning. Seems like the module compiles successfully but the linking to rust library is broken.

Let me know if more information is needed to debug this issue. [0]:

dipanjan

dipanjan

0

The project doesn't get compiled out of the box with rustc 1.20.0-nightly (bf0a9e0b4 2017-07-10). Instead of the forked version of bindgen (which doesn't get compiled), I used the original one which generates a kernel binding that uses std crate everywhere. A snippet looks like:

While compiling, I get the following errors (a lot of similar ones because of use of std crate).

I wonder how the original project was even compiled. Any idea how can I get around the issue?

tbelaire

tbelaire

1

I've been forced to remove the --gc-sections line, as it removes functions, including _Unwind_Resume, causing errors at link time. This is only apparent if you've started using something from the stdlib that can panic, as otherwise there are no references to _Unwind_Resume, but for my rot13 branch, I have been unable to build with --gc-sections.

Information - Updated Jan 15, 2022

Stars: 821
Forks: 71
Issues: 10

Repositories & Extras

Actix

7.2K

Actix Rust Framework for web and wasm based applications

Rust's premier framework for handling large scale web applications across a wide varaitey of operating systems

Actix Rust Framework for web and wasm based applications

gaol is a cross-platform, operating-system-level application sandboxing library written in Rust

It allows you to restrict the set of operations that your application is allowed to perform, to provide a layer of defense against malicious or...

gaol is a cross-platform, operating-system-level application sandboxing library written in Rust

gaol is a cross-platform, operating-system-level application sandboxing library written in Rust

It allows you to restrict the set of operations that your application is allowed to perform, to provide a layer of defense against malicious or...

gaol is a cross-platform, operating-system-level application sandboxing library written in Rust

AerOS, the evolution of Birb OS

Now, a real operating system written in Rust

AerOS, the evolution of Birb OS

uhyve - A minimal hypervisor for RustyHermit

uhyve is small hypervisor to boot the library operating systems Rust website and follow the installation instructions

uhyve - A minimal hypervisor for RustyHermit

A rust library for system information analytics and monitoring

Siquery provides utilities to explore low level operating system data on mac, windows and linux in an efficient and intuitive way by integrating an SQLite...

A rust library for system information analytics and monitoring

A Rust interface to interact with operating systems based on μITRON or its derivative

Rust interface to interact with operating systems based on

A Rust interface to interact with operating systems based on μITRON or its derivative

Eclipse Paho MQTT Rust Client Library

Eclipse Paho MQTT Rust client library on memory-managed operating systems such as Linux/Posix, Mac, and Windows

Eclipse Paho MQTT Rust Client Library

Operating System development tutorials in Rust on the Raspberry Pi

The tutorials will give a guided, step-by-step tour of how to write a @andre-richter)

Operating System development tutorials in Rust on the Raspberry Pi

XRS-OS (🚧WIP)

Xrs is a POSIX-subset operating system kernel written in Rust

XRS-OS (🚧WIP)

A Rust library for retrieving random data from (operating) system source

assumed that system always provides high-quality cryptographically secure random

A Rust library for retrieving random data from (operating) system source

The trash is a Rust library for moving files and folders to the operating system's...

The trash is a Rust library for moving files and folders to the operating system's Recycle Bin or Trash or Rubbish Bin or what have...

The trash is a Rust library for moving files and folders to the operating system's...
Facebook Instagram Twitter GitHub Dribbble
Privacy