Rux, a microkernel written in Rust
Rux is a hobbyist microkernel written in Rust, featuring a capability-based system similar to seL4.
Overview
Rux's goal is to become a safe general-purpose microkernel. It tries to take advantage of Rust's memory model -- ownership and lifetime. While the kernel will be small, unsafe code should be kept minimal. This makes updating functionalities of the kernel hassle-free.
Rux uses a design that is similar to seL4. While there won't be formal verification in the short term, it tries to address some design issues of seL4, for example, capability allocation.
Contributing
We use Phabricator to manage
code reviews and collabration. To submit a patch, install
arcanist. After
you finished coding, run arc diff and it will guide you to create a
new patch in Phabricator.
If you don't like arcanist, you can also submit raw diff directly through the web interface. Refer to guide in this page for details on how to do this.
Quickstart
Currently, due to packaging problem, the kernel is only tested to
compile and run on Linux with x86_64. Platforms with qemu and compiler
target of x86_64 should all be able to run this kernel, but do it at
your own risk.
To run the kernel, first install Rust, qemu, and cross-compiled
GNU's binutils. The easiest way to do it is through the
default.nix file provided in the source code. Install
Nix, then go to the source code root and run
the following command:
nix-shell
After that, run:
make run
You should see the kernel start to run with a qemu VGA buffer. The
buffer, after the kernel successfully booted, should show a simple
command-line interface controlled by rinit program launched by the
kernel. Several commands can be used to test things out.
echo [message]
Echo messages and print them back to the VGA buffer.
list
Print the current CPool slots into the kernel message buffer.
retype cpool [source slot id] [target slot id]
Retype an Untyped capability into a CPool capability. [source slot id]
should be a valid slot index of an Untyped capability. [target slot id]
should be an empty slot for holding the retyped CPool capability.
Example: Talk With a Child Task
The rinit program will start the command line interface when it is the first to run. For all subsequent rinit programs, they will wait on a channel (using the root CPool of index 255), and print out the value to the serial buffer.
When you see the command line in the qemu VGA buffer, the "parent" rinit program has been successfully started. We can then create a "child" program using the same memory layout (sharing one page table), and make them talk.
When the "parent" rinit program is started, you should see something like below in the VGA buffer:
Child entry should be at: 0x88b0 (34992)
Child stack pointer should be at: 0x70003ffc (1879064572)
Those messages are useful if we want to create a "child".
To do this, we first retype a new task from an untyped capability.
retype task 2 249
This creates a new task in "inactive" state, which allows us to do further settings. We then set its stack pointer and instruction pointer to the valid value:
set stack 249 1879064572
set instruction 249 34992
Then we set the task's root CPool and top page table the same as the "parent":
set cpool 249 0
set table 249 3
The task buffer is used for system calls, thus we need a new one for
the child. Fortunately, in the kernel kmain, we have already created
one at index 250, so we can set that as the "child"'s buffer.
set buffer 249 250
After that, we can set the state of the task to active. This will start the task.
set active 249 1
If you are lazy and don't want to create the task from scratch. The command below automates the task from retyping tasks from untyped to activating the task.
start child
After the child has started, we can send numbers to channel (with CPool index 255).
send raw 5
You should see [kernel] Userspace print: Received from master: 5 in
the serial message buffer.
You can also send capabilities over the channel. Rux uses different
system calls to send raw values, payloads and capabilities through
channels. If you wish to send capabilities, modify let value: u64 = system::channel_take(CAddr::from(255)); in child_main of
rinit/src/lib.rs to let value: CAddr = system::channel_take_cap(CAddr::from(255));.
send cap 0
And the top-level capability pool capability (CPoolCap) is copied again from parent to child.
Source Code Structure
The development of Rux happen in the master branch in the source code
tree. The kernel resides in the kernel folder, with platform-specific
code in kernel/src/arch. For the x86_64 platform, the kernel is
booted from kernel/src/arch/x86_64/start.S. The assembly code them
jumps to the kinit function in kernel/src/arch/x86_64/init/mod.rs.
After the kernel is bootstrapped, it will initialize a user-space
program called rinit, which resides in the rinit folder. The
user-space program talks with the kernel through system calls, with ABI
defined in the package abi, and wrapped in system.
Kernel Design
Capabilities
Capabilities are used in kernel to manage Kernel Objects. Those Capabilities are reference-counted pointers that provide management for object lifecycles.
Capabilities in user-space can be accessed using so-called CAddress,
refered through the root capability of the user-space task. This helps
to handle all permission managements for the kernel, and thus no
priviliged program or account is needed.
Current implemented capabilities are:
- Untyped memory capability (UntypedCap)
- Capability pool capability (CPoolCap)
- Paging capability
- PML4Cap, PDPTCap, PDCap, PTCap
- RawPageCap, TaskBufferPageCap
- VGA buffer
- CPU time sharing capability (TaskCap)
- Inter-process communication capability (ChannelCap)
Example: Initialize a New Task
This example shows how to initialize a new task using the capability system.
- Create an empty TaskCap.
- Create an empty CPoolCap.
- Initialize paging capabilities (One PML4Cap, Several PDPTCap, PDCap, PTCap and RawPageCap)
- Assign the stack pointer in TaskCap.
- Load the program into those RawPageCap.
- Assign the PML4Cap to TaskCap.
- Assign the CPoolCap to TaskCap.
- Switch to the task!
Implementation
Implementing reference-counted object is a little bit tricky in kernel,
as objects need to be immediately freed, and all weak pointers need to
be cleared after the last strong pointer goes out. Rux's implementation
uses something called WeakPool to implement this. The original
reference counted object (called Inner), form a double-linked list
into the nodes in multiple WeakPools.
Capability Pools
Capability Pools (or CPool) are used to hold multiple capability
together. This is useful for programs to pass around permissions, and is
essential for CPool addressing. In implementation, capability pools
are implemented as a WeakPool.
Tasks
A task capability has a pointer to a capability pool (the root for
CPool addressing), a task buffer (for kernel calls), and a top-level
page table. When switching to a task, the kernel switches to the page
table specified.
The switch_to function implemented uses several tricks to make it
"safe" as in Rust's sense. When an interrupt happens in userspace, the
kernel makes it as if the switch_to function has returned.
In kernel-space, interrupts are disabled.
Channels
Tasks communicate with each other through channels. A channel has a
short buffer holding messages sent from a task, and will respond this to
the first task that calls wait on the channel.