RuxOS

A unikernel operating system written in Rust.

RuxOS was inspired by Unikraft and ArceOS

🚧 Working In Progress. See RuxOS Book for more information.

Features & TODOs

• Architecture: x86_64, riscv64, aarch64
• Platform: QEMU pc-q35 (x86_64), virt (riscv64/aarch64)
• Multi-thread
• FIFO/RR/CFS scheduler
• VirtIO net/blk/gpu drivers
• TCP/UDP net stack using smoltcp
• Synchronization/Mutex
• SMP scheduling with single run queue
• File system
• Compatible with Linux apps
• Dynamically loading apps
• Interrupt driven device I/O
• Async I/O

Example apps

Example applications can be found in the apps/ directory. All applications must at least depend on the following modules, while other modules are optional:

• ruxruntime: Bootstrapping from the bare-metal environment, and initialization.
• ruxhal: Hardware abstraction layer, provides unified APIs for cross-platform.
• ruxconfig: Platform constants and kernel parameters, such as physical memory base, kernel load addresses, stack size, etc.
• axlog: Multi-level formatted logging.

The currently supported applications and programming languages, as well as their dependent modules and features, are shown in the following table:

Rust applications

App	Extra modules	Enabled features	Description
display	axalloc, ruxdisplay	alloc, paging, display	Graphic/GUI test
shell	axalloc, ruxdriver, ruxfs	alloc, paging, fs	A simple shell that responds to filesystem operations

C applications

App	Enabled features	Description
helloworld		A minimal app that just prints a string by C
envtest	alloc, paging	An environment variable test
memtest	alloc, paging	Dynamic memory allocation test by C
filetest	alloc, paging, fs, blkfs	File system operation test
httpclient	alloc, paging, net	A simple client that sends an HTTP request and then prints the response by C
httpserver	alloc, paging, net	A multi-threaded HTTP server that serves a static web page by C
udpserver	alloc, paging, net	A simple UDP server that send back original message
systime	rtc	A simple test for real time clock module
basic	alloc, paging, multitask, irq	A simple test for basic pthread-related API in C standard library
parallel	alloc, paging, multitask	Parallel computing test to test synchronization by C
pipe	alloc, paging, multitask, pipe	A test for pipe API
sleep	alloc, paging, multitask, irq	Thread sleeping test
tsd	alloc, paging, multitask, irq	A test for pthread-key related API
dl	paging, alloc, irq, musl, multitask, fs, pipe, poll, rtc, signal, virtio-9p	An example for dynamically loading apps
libc-bench	alloc, multitask, fs, musl	A standard libc test for musl libc integration
sqlite3	alloc, paging, fs, fp_simd, blkfs	A simple test for Sqlite3 API
iperf	alloc, paging, net, fs, blkfs, select, fp_simd	A network performance test tool
redis	alloc, paging, fp_simd, irq, multitask, fs, blkfs, net, pipe, epoll, poll, virtio-9p, rtc	Redis server on Ruxos
cpp	alloc, paging, irq, multitask, fs, random-hw	C++ benchmark
nginx	alloc, paging, fp_simd, irq, multitask, fs, blkfs, net, pipe, epoll, poll, select, rtc, signal	Run Nginx as web server
wamr	alloc, paging, fp_simd, irq, multitask, fs, virtio-9p, signal, smp	Wasm runtime

Programming languages

Language	Description
C	Run C apps by RuxOS ruxlibc or standard musl libc supported by ruxmusl. Evaluated by libc-bench.
C++	Run C++ apps by c++ static library provided by musl libc. Passed c++ benchmark. Evaluated by c++ benchmark.
Perl	Run Perl standard library by musl libc. Evaluated by Perl benchmark.
Python	Run Python apps by dynamically loading Python modules. Evaluated by Python benchmark.
Rust	Run Rust standard library by modifying Rust std source. Evaluated by Rust tests.

Build & Run

Install build dependencies

Install cargo-binutils to use rust-objcopy and rust-objdump tools:

cargo install cargo-binutils

for build&run C apps

Install libclang-dev:

sudo apt install libclang-dev

Download&Install cross-musl-based toolchains:

# download
wget https://musl.cc/aarch64-linux-musl-cross.tgz
wget https://musl.cc/riscv64-linux-musl-cross.tgz
wget https://musl.cc/x86_64-linux-musl-cross.tgz
# install
tar zxf aarch64-linux-musl-cross.tgz
tar zxf riscv64-linux-musl-cross.tgz
tar zxf x86_64-linux-musl-cross.tgz
# exec below command in bash OR add below info in ~/.bashrc
export PATH=`pwd`/x86_64-linux-musl-cross/bin:`pwd`/aarch64-linux-musl-cross/bin:`pwd`/riscv64-linux-musl-cross/bin:$PATH

Example apps

# in ruxos directory
make A=path/to/app ARCH=<arch> LOG=<log>

Where <arch> should be one of riscv64, aarch64，x86_64.

<log> should be one of off, error, warn, info, debug, trace.

path/to/app is the relative path to the example application.

More arguments and targets can be found in Makefile.

For example, to run the shell on qemu-system-aarch64:

make A=apps/fs/shell ARCH=aarch64 LOG=info run BLK=y

Note that the BLK=y argument is required to enable the block device in QEMU. These arguments (NET, GRAPHIC, etc.) only take effect at runtime not build time.

Your custom apps

Rust

1. Create a new rust package with no_std and no_main environment.

2. Add axstd dependency and features to enable to Cargo.toml:

   [dependencies]
   axstd = { path = "/path/to/ruxos/ulib/axstd", features = ["..."] }

3. Call library functions from axstd in your code, just like the Rust std library.

4. Build your application with RuxOS, by running the make command in the application directory:

   # in app directory
   make -C /path/to/ruxos A=$(pwd) ARCH=<arch> run
   # more args: LOG=<log> SMP=<smp> NET=[y|n] ...

   All arguments and targets are the same as above.

C

1. Create axbuild.mk and features.txt in your project:

   app/
   ├── foo.c
   ├── bar.c
   ├── axbuild.mk      # optional, if there is only one `main.c`
   └── features.txt    # optional, if only use default features

2. Add build targets to axbuild.mk, add features to enable to features.txt (see this example):

   # in axbuild.mk
   app-objs := foo.o bar.o

   # in features.txt
   alloc
   paging
   net

3. Build your application with RuxOS, by running the make command in the application directory:

   # in app directory
   make -C /path/to/ruxos A=$(pwd) ARCH=<arch> run
   # more args: LOG=<log> SMP=<smp> NET=[y|n] ...

How to build RuxOS for specific platforms and devices

Set the PLATFORM variable when run make:

# Build helloworld for raspi4
make PLATFORM=aarch64-raspi4 A=apps/helloworld

You may also need to select the corrsponding device drivers by setting the FEATURES variable:

# Build the shell app for raspi4, and use the SD card driver
make PLATFORM=aarch64-raspi4 A=apps/fs/shell FEATURES=driver-bcm2835-sdhci
# Build Redis for the bare-metal x86_64 platform, and use the ixgbe and ramdisk driver
make PLATFORM=x86_64-pc-oslab A=apps/c/redis FEATURES=driver-ixgbe,driver-ramdisk SMP=4

RuxGo

A convient tool to run RuxOS applications by concise command. See RuxGo-Book for more information.

Design