tim-c1 / arceos

An experimental modular OS written in Rust.

ArceOS

An experimental modular operating system (or unikernel) written in Rust.

ArceOS was inspired a lot by Unikraft.

🚧 Working In Progress.

Contributing to arceos

1. fork this repo's branch dev to your own repo
2. add&update codes in your own repo's dev branch, pass CI test
3. create PR to this repo's branch dev
4. discuss with other contributors, merge PR to this repo's branch dev
5. owners merge this repo's branch dev to main

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
• 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:

• axruntime: Bootstrapping from the bare-metal environment, and initialization.
• axhal: Hardware abstraction layer, provides unified APIs for cross-platform.
• axconfig: 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:

App	Extra modules	Enabled features	Description
helloworld			A minimal app that just prints a string
exception		paging	Exception handling test
memtest	axalloc	alloc, paging	Dynamic memory allocation test
display	axalloc, axdisplay	alloc, paging, display	Graphic/GUI test
yield	axalloc, axtask	alloc, paging, multitask, sched_fifo	Multi-threaded yielding test
parallel	axalloc, axtask	alloc, paging, multitask, sched_fifo	Parallel computing test (to test synchronization & mutex)
sleep	axalloc, axtask	alloc, paging, multitask, sched_fifo	Thread sleeping test
shell	axalloc, axdriver, axfs	alloc, paging, fs	A simple shell that responds to filesystem operations
httpclient	axalloc, axdriver, axnet	alloc, paging, net	A simple client that sends an HTTP request and then prints the response
echoserver	axalloc, axdriver, axnet, axtask	alloc, paging, net, multitask	A multi-threaded TCP server that reverses messages sent by the client
httpserver	axalloc, axdriver, axnet, axtask	alloc, paging, net, multitask	A multi-threaded HTTP server that serves a static web page

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 arceos directory
make A=path/to/app ARCH=<arch> LOG=<log> NET=[y|n] FS=[y|n]

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 httpserver on qemu-system-aarch64 with 4 cores:

make A=apps/net/httpserver ARCH=aarch64 LOG=info NET=y SMP=4 run

Your custom apps

Rust

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

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

   [dependencies]
   libax = { path = "/path/to/arceos/ulib/libax", features = ["..."] }

3. Call library functions from libax in your code, like the helloworld example.

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

   # in app directory
   make -C /path/to/arceos 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
   default
   alloc
   paging
   net

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

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

Design