ArceOS

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

ArceOS was inspired a lot by Unikraft.

🚧 Working In Progress.

Features & TODOs

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: Bootstraping 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 log definition and printing.

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

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.

<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

Create a new rust package with no_std and no_main environment.

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

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

Call library functions from libax in your code, like the helloworld example.
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

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

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
```

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] ...

c0per/arceos

ArceOS

Features & TODOs

Example apps

Build & Run

Install build dependencies

Example apps

Your custom apps

Rust

C

Design