Awkernel

Awkernel is a safe and realtime operating system. It can execute async/await applications in kernel space safely.

Dependencies

Compiler Tools

$ sudo apt install clang qemu-system-arm qemu-system-x86 qemu-system-misc python3-pyelftools
$ rustup toolchain install nightly-2026-07-20
$ rustup default nightly-2026-07-20
$ rustup component add rust-src llvm-tools-preview
$ rustup target add x86_64-unknown-none aarch64-unknown-none riscv64gc-unknown-none-elf riscv32imac-unknown-none-elf

Documentation Tools

$ cargo install cargo-binutils
$ curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
$ cargo binstall mdbook
$ cargo binstall mdbook-mermaid

Crates

• kernel
  • boot code
  • initialization
    • virtual memory
    • heap memory
    • stack memory
    • devices (UART, etc)
• awkernel_lib
  • library used by both kernel and awkernel_async_lib
• awkernel_async_lib
  • asynchronous library for no_std
• awkernel_async_lib_verified
  • verified library for awkernel_async_lib
  • pure Rust (no dependencies on external functions and no inline assembly)
• awkernel_futures_macro
• awkernel_drivers
• awkernel_aarch64
• userland
• applications
  • awkernel_shell

graph TD;
    awkernel_async_lib-->awkernel_async_lib_verified;
    awkernel_async_lib-->awkernel_futures_macro;
    awkernel_lib-->awkernel_aarch64;
    awkernel_async_lib-->awkernel_lib;
    awkernel_lib-->awkernel_sync;
    userland-->awkernel_async_lib;
    kernel-->awkernel_lib;
    kernel-->awkernel_async_lib;
    kernel-->awkernel_aarch64;
    kernel-->awkernel_drivers;
    awkernel_drivers-->awkernel_lib;
    kernel-->userland;

Loading

Applications can use awkernel_async_lib, awkernel_lib, and awkernel_drivers.

---

Documents

$ make docs
$ ls docs/index.html

Raspi

$ cargo doc_raspi
$ ls target/aarch64-kernel/doc/awkernel/index.html
$ ls target/aarch64-kernel/doc/awkernel_lib/index.html
etc

AArch64 Qemu Virt

$ cargo doc_aarch64_virt
$ ls target/aarch64-kernel/doc/awkernel/index.html
$ ls target/aarch64-kernel/doc/awkernel_lib/index.html
etc

x86_64

$ make kernel/asm/x86
$ cargo doc_x86
$ ls target/x86_64-kernel/doc/awkernel/index.html
$ ls target/aarch64-kernel/doc/awkernel_lib/index.html
etc

---

x86_64

Compile

Release build (recommended).

$ make x86_64 RELEASE=1

Debug build.

$ make x86_64

Developing for x86_64 on macOS

kernel/asm/x86/mpboot.S mixes 16/32/64-bit code and needs a real GNU assembler and linker. By default, Apple systems provide an alias so gcc points to clang. Also, modern Apple Silicon processors are aarch64. Therefore, we must install a GNU x86_64 ELF cross toolchain:

$ brew install x86_64-elf-gcc x86_64-elf-binutils

Then, when building your application, point to this specific cross toolchain:

$ make x86_64 RELEASE=1 CROSS_COMPILE=x86_64-elf-

Important

Do not remove the trailing -

This way, Awkernel will use the x86_64-elf-gcc compiler and the x86_64-elf-ld linker.

Boot

Qemu 8.x or later is required. Qemu 6.x is not supported.

$ make qemu-x86_64

GDB

$ make debug-x86_64
$ make gdb-x86_64

---

AArch64 Qemu Virt

Compile

Release build (recommended).

$ make aarch64 BSP=aarch64_virt RELEASE=1

Debug build.

$ make aarch64 BSP=aarch64_virt

Boot

$ make qemu-aarch64-virt

GDB

$ make debug-aarch64_virt
$ make gdb-aarch64_virt

---

Raspberry Pi 3 (AArch64, Qemu) or Raspberry Pi Zero 2 W

Compile

Release build (recommended). RELEASE=1 must be used for actual devices.

$ make aarch64 BSP=raspi3 RELEASE=1

Debug build.

$ make aarch64 BSP=raspi3

Boot

$ make qemu-raspi3

GDB

$ make debug-raspi3
$ make gdb-raspi3

---

Raspberry Pi 4 (AArch64)

Compile

Specify Release=1.

$ make aarch64 BSP=raspi4 RELEASE=1

Boot

• Serial
  • port: GPIO 14 (Tx) and 15 (Rx)
  • 8N1: eight data bits, no parity, one stop bit
  • Speed: 115200

---

Raspberry Pi 5 (AArch64)

Compile

Specify Release=1.

$ make aarch64 BSP=raspi5 RELEASE=1

Boot

• Serial
  • port: GPIO 14 (Tx) and 15 (Rx)
  • 8N1: eight data bits, no parity, one stop bit
  • Speed: 115200

---

RISC-V (64bit, Qemu)

Compile

Release build (recommended).

$ make riscv64 RELEASE=1

Debug build.

$ make riscv64

Boot

$ make qemu-riscv64

---

RISC-V (32bit, Qemu)

Compile

Release build (recommended).

$ make riscv32 RELEASE=1

Debug build.

$ make riscv32

Boot

$ make qemu-riscv32

---

Linux / macOS

Compile

Debug build.

$ make std

Release build.

$ make std RELEASE=1

Boot

Debug build.

$ make run-std

Release build.

$ make run-std RELEASE=1

Qemu Monitor

$ make qemu-raspi3
$ telnet localhost 5556

---

Test

Unit tests by using Rust's mechanism can be executed as follows.

$ make test

Some mechanisms which use atomic instructions are verified by using loom, and these verifications are executed as follows. It will takes several minutes.

$ make loom

CI Checks

scripts/ci.sh runs the same checks as the CI. It requires cargo-udeps in addition to the compiler tools.

$ cargo binstall cargo-udeps
$ scripts/ci.sh

Cargo.lock is not tracked, so the CI uses the latest compatible dependencies. If a check fails only on your machine, run cargo update and try again.

To run the checks with pre-commit, install the hooks. The pre-commit hook runs cargo fmt --check, and the pre-push hook runs scripts/ci.sh.

$ pre-commit install

Running CI Checks on macOS

scripts/ci.sh invokes x86_64 builds via make check_x86_64 and make udeps. As cargo-udeps checks the x86 feature against the x86_64-unknown-linux-gnu target, that target must also be installed for the pinned nightly toolchain:

$ rustup target add x86_64-unknown-linux-gnu

Therefore, as done for compiling x86 projects, you mut define the CROSS_COMPILE variable:

$ CROSS_COMPILE=x86_64-elf- scripts/ci.sh

Important

Do not remove the trailing - of x86_64-elf-

Publications

Publications

Specification and Test Results

Specification and Test Results