miochyann / ruxos

Rust Unikernel OS

RuxOS

An experimental modular operating system (or unikernel) 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 (Rust), as well as their dependent modules and features, are shown in the following table:

Rust

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

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
libc-bench	alloc, multitask, fs, musl	A standard libc test for musl libc integration
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	A Redis server on Ruxos
sqlite3	alloc, paging, fs, fp_simd, blkfs	A simple test for Sqlite3 API
cpp	alloc, paging, irq, multitask, fs, random-hw	C++ benchmark
dl	paging, alloc, irq, musl, multitask, fs, pipe, poll, rtc, signal, virtio-9p	An example for dynamically loading apps

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

Design