Creating an OS Project

The OSDK can be used to create a new kernel project or a new library project. A kernel project defines the entry point of the kernel and can be run with QEMU. A library project can provide certain OS functionalities and be imported by other OSes.

Creating a new kernel project

Creating a new kernel project is simple. You only need to execute the following command:

cargo osdk new --kernel myos

Creating a new library project

Creating a new library project requires just one command:

cargo osdk new mylib

Generated files

Next, we will introduce the contents of the generated project in detail. If you don't wish to delve into the details, you can skip the following sections.

Overview

The generated directory for both the kernel project and library project contains the following contents:

myos/
├── Cargo.toml
├── OSDK.toml
├── rust-toolchain.toml
└── src/
    └── lib.rs

src/lib.rs

Kernel project

The src/lib.rs file contains the code for a simple kernel. The function marked with the #[ostd::main] macro is considered the kernel entry point by OSDK. The kernel will print Hello world from the guest kernel!to the console and then abort.

#![no_std]
#![deny(unsafe_code)]

use ostd::prelude::*;

#[ostd::main]
fn kernel_main() {
    println!("Hello world from guest kernel!");
}

Library project

The src/lib.rs of library project only contains a simple kernel mode unit test. It follows a similar code pattern as user mode unit tests. The test module is marked with the #[cfg(ktest)] macro, and each test case is marked with #[ktest].

#![no_std]
#![deny(unsafe_code)]

#[cfg(ktest)]
mod tests {
    use ostd::prelude::*;

    #[ktest]
    fn it_works() {
        let memory_regions = ostd::boot::memory_regions();
        assert!(!memory_regions.is_empty());
    }
}

Cargo.toml

The Cargo.toml file is the Rust project manifest. In addition to the contents of a normal Rust project, OSDK will add the dependencies of the Asterinas OSTD to the file. The dependency version may change over time.

[dependencies.ostd]
git = "https://github.com/asterinas/asterinas"
branch = "main"

OSDK will also exclude the directory which is used to generate temporary files.

[workspace]
exclude = ["target/osdk/base"]

OSDK.toml

The OSDK.toml file is a manifest that defines the exact behavior of OSDK. By default, it includes settings on how to start QEMU to run a kernel. The meaning of each key can be found in the manifest documentation. Please avoid changing the default settings unless you know what you are doing.

The default manifest of a kernel project:

project_type = "kernel"

[boot]
method = "grub-rescue-iso"

[qemu]
args = """\
    -machine q35,kernel-irqchip=split \
    -cpu Icelake-Server,+x2apic \
    --no-reboot \
    -m 8G \
    -smp 1 \
    -nographic \
    -serial chardev:mux \
    -monitor chardev:mux \
    -chardev stdio,id=mux,mux=on,signal=off \
    -display none \
    -device isa-debug-exit,iobase=0xf4,iosize=0x04 \
    -drive if=pflash,format=raw,unit=0,readonly=on,file=/usr/share/OVMF/OVMF_CODE.fd \
    -drive if=pflash,format=raw,unit=1,file=/usr/share/OVMF/OVMF_VARS.fd \
"""

rust-toolchain.toml

The Rust toolchain for the kernel. It is the same as the toolchain of the Asterinas OSTD.