Merge pull request #166 from rust-osdev/examples

Add some usage examples

Author: phil-opp

.github/workflows/build.yml

@@ -69,6 +69,14 @@ jobs:
         with:
           command: test
 
+      - name: "Example: `basic`"
+        working-directory: examples/basic
+        run: cargo kimage
+
+      - name: "Example: `test_framework` example"
+        working-directory: examples/test_framework
+        run: cargo ktest
+
   fmt:
     name: Check Formatting
     runs-on: ubuntu-latest

Cargo.toml

@@ -15,6 +15,10 @@ members = [
     "tests/test_kernels/map_phys_mem",
     "tests/test_kernels/higher_half",
 ]
+exclude = [
+    "examples/basic",
+    "examples/test_framework",
+]
 
 [[bin]]
 name = "builder"

examples/README.md

@@ -0,0 +1,4 @@
+## Usage Examples
+
+- [`basic`](basic)
+- [`test_framework`](test_framework)

examples/basic/.cargo/config.toml

@@ -0,0 +1,7 @@
+[target.'cfg(target_os = "none")']
+runner = "cargo run --package simple_boot --"
+
+[alias]
+kbuild = "build --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem"
+kimage = "run --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem -- --no-run"
+krun = "run --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem"

examples/basic/.gitignore

@@ -0,0 +1 @@
+target

examples/basic/Cargo.lock

@@ -0,0 +1,14 @@
+[package]
+name = "basic_example"
+version = "0.1.0"
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[workspace]
+members = [
+    "simple_boot",
+]
+
+[dependencies]
+bootloader = { path = "../.." } # replace this with a version number

examples/basic/Cargo.toml

@@ -0,0 +1,17 @@
+# Basic Example
+
+This a minimal example how to create a bootable disk image with the `bootloader` crate.
+
+## Structure
+
+The kernel code is in `src/main.rs`. It requires some special build instructions to recompile the `core` library for the custom target defined in `x86_64-custom.json`. It depends on the `bootloader` crate for booting..
+
+The `simple_boot` sub-crate is responsible for combining the kernel with the bootloader to create bootable disk images. It is configured as a [custom _runner_](https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner), which means that cargo will automatically invoke it on `cargo run`. The compiled kernel will hereby be passed as an argument.
+
+## Build Commands
+
+The `.cargo/config.toml` file defines command aliases for the common commands:
+
+- To build the kernel, run **`cargo kbuild`**.
+- To build the kernel and turn it into a bootable disk image, run **`cargo kimage`** (short for "kernel image"). This will invoke our `boot` sub-crate with an additional `--no-run` argument so that it just creates the disk image and exits.
+- To additionally run the kernel in QEMU after creating the disk image, run **`cargo krun`**.

examples/basic/README.md

@@ -0,0 +1,11 @@
+[package]
+name = "simple_boot"
+version = "0.1.0"
+authors = ["Philipp Oppermann <[email protected]>"]
+edition = "2018"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+bootloader-locator = "0.0.4" # for locating the `bootloader` dependency on disk
+locate-cargo-manifest = "0.2.0" # for locating the kernel's `Cargo.toml`

examples/basic/simple_boot/Cargo.toml

@@ -0,0 +1,78 @@
+use std::{
+    path::{Path, PathBuf},
+    process::Command,
+};
+
+const RUN_ARGS: &[&str] = &["--no-reboot", "-s"];
+
+fn main() {
+    let mut args = std::env::args().skip(1); // skip executable name
+
+    let kernel_binary_path = {
+        let path = PathBuf::from(args.next().unwrap());
+        path.canonicalize().unwrap()
+    };
+    let no_boot = if let Some(arg) = args.next() {
+        match arg.as_str() {
+            "--no-run" => true,
+            other => panic!("unexpected argument `{}`", other),
+        }
+    } else {
+        false
+    };
+
+    let bios = create_disk_images(&kernel_binary_path);
+
+    if no_boot {
+        println!("Created disk image at `{}`", bios.display());
+        return;
+    }
+
+    let mut run_cmd = Command::new("qemu-system-x86_64");
+    run_cmd
+        .arg("-drive")
+        .arg(format!("format=raw,file={}", bios.display()));
+    run_cmd.args(RUN_ARGS);
+
+    let exit_status = run_cmd.status().unwrap();
+    if !exit_status.success() {
+        std::process::exit(exit_status.code().unwrap_or(1));
+    }
+}
+
+pub fn create_disk_images(kernel_binary_path: &Path) -> PathBuf {
+    let bootloader_manifest_path = bootloader_locator::locate_bootloader("bootloader").unwrap();
+    let kernel_manifest_path = locate_cargo_manifest::locate_manifest().unwrap();
+
+    let mut build_cmd = Command::new(env!("CARGO"));
+    build_cmd.current_dir(bootloader_manifest_path.parent().unwrap());
+    build_cmd.arg("builder");
+    build_cmd
+        .arg("--kernel-manifest")
+        .arg(&kernel_manifest_path);
+    build_cmd.arg("--kernel-binary").arg(&kernel_binary_path);
+    build_cmd
+        .arg("--target-dir")
+        .arg(kernel_manifest_path.parent().unwrap().join("target"));
+    build_cmd
+        .arg("--out-dir")
+        .arg(kernel_binary_path.parent().unwrap());
+    build_cmd.arg("--quiet");
+
+    if !build_cmd.status().unwrap().success() {
+        panic!("build failed");
+    }
+
+    let kernel_binary_name = kernel_binary_path.file_name().unwrap().to_str().unwrap();
+    let disk_image = kernel_binary_path
+        .parent()
+        .unwrap()
+        .join(format!("boot-bios-{}.img", kernel_binary_name));
+    if !disk_image.exists() {
+        panic!(
+            "Disk image does not exist at {} after bootloader build",
+            disk_image.display()
+        );
+    }
+    disk_image
+}

examples/basic/simple_boot/src/main.rs

@@ -0,0 +1,24 @@
+#![no_std]
+#![no_main]
+
+use bootloader::{entry_point, BootInfo};
+use core::panic::PanicInfo;
+
+entry_point!(kernel_main);
+
+fn kernel_main(boot_info: &'static mut BootInfo) -> ! {
+    // turn the screen gray
+    if let Some(framebuffer) = boot_info.framebuffer.as_mut() {
+        for byte in framebuffer.buffer_mut() {
+            *byte = 0x90;
+        }
+    }
+
+    loop {}
+}
+
+
+#[panic_handler]
+fn panic(_info: &PanicInfo) -> ! {
+    loop {}
+}

examples/basic/src/main.rs

@@ -0,0 +1,15 @@
+{
+    "llvm-target": "x86_64-unknown-none",
+    "data-layout": "e-m:e-i64:64-f80:128-n8:16:32:64-S128",
+    "arch": "x86_64",
+    "target-endian": "little",
+    "target-pointer-width": "64",
+    "target-c-int-width": "32",
+    "os": "none",
+    "executables": true,
+    "linker-flavor": "ld.lld",
+    "linker": "rust-lld",
+    "panic-strategy": "abort",
+    "disable-redzone": true,
+    "features": "-mmx,-sse,+soft-float"
+  }

examples/basic/x86_64-custom.json

@@ -0,0 +1,8 @@
+[target.'cfg(target_os = "none")']
+runner = "cargo run --package boot --"
+
+[alias]
+kbuild = "build --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem"
+kimage = "run --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem -- --no-run"
+krun = "run --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem"
+ktest = "test --target x86_64-custom.json -Zbuild-std=core -Zbuild-std-features=compiler-builtins-mem"

examples/test_framework/.cargo/config.toml

@@ -0,0 +1 @@
+target