Creating an OS Project
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 #[aster_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.
There is also a code snippet that demonstrates
how to write kernel mode unit tests.
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]
#![forbid(unsafe_code)]
use aster_frame::prelude::*;
#[aster_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.
#![no_std]
#![forbid(unsafe_code)]
#[macro_use]
extern crate ktest;
extern crate aster_frame;
#[cfg(ktest)]
mod tests {
#[ktest]
fn it_works() {
let memory_regions = aster_frame::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 framework to the file.
The dependency version may change over time.
[dependencies.aster_frame]
git = "https://github.com/asterinas/asterinas"
branch = "main"
[dependencies.ktest]
git = "https://github.com/asterinas/asterinas"
branch = "main"
OSDK.toml
The OSDK.toml
file is a manifest
that defines the exact behavior of OSDK.
By default, it contains the following contents.
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.
project_type = "lib"
[boot]
method = "qemu-direct"
[qemu]
args = """\
-machine q35,kernel-irqchip=split \
-cpu Icelake-Server,+x2apic \
--no-reboot \
-m 2G \
-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 \
"""
rust-toolchain.toml
The Rust toolchain for the kernel. It aligns with the toolchain of the Asterinas framework.