Skip to content

cylindrical2002/arceos

 
 

Repository files navigation

ArceOS

CI CI Docs

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, aarch64x86_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

About

An experimental modular OS written in Rust.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Rust 84.3%
  • C 12.4%
  • Assembly 1.5%
  • Makefile 1.3%
  • Shell 0.5%