Rux, a microkernel written in Rust
Rux is a hobbyist microkernel written in Rust, featuring a capability-based system similar to seL4.
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.
Currently, due to packaging problem, the kernel is only tested to
compile and run on Linux with
x86_64. Platforms with qemu and compiler
x86_64 should all be able to run this kernel, but do it at
your own risk.
To run the kernel, first install
qemu, and cross-compiled
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:
After that, 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 messages and print them back to the VGA buffer.
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.
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
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
kernel/src/arch. For the
x86_64 platform, the kernel is
kernel/src/arch/x86_64/start.S. The assembly code them
jumps to the
kinit function in
After the kernel is bootstrapped, it will initialize a user-space
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
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
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!
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 (or
CPool) are used to hold multiple capability
together. This is useful for programs to pass around permissions, and is
CPool addressing. In implementation, capability pools
are implemented as a
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
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.
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.