Springboard

VERSION: 3.0.1/EARLY/UNRELEASED
LICENSE: Apache-2.0
README: Where would you rather be?
INFO:

The upstream bootloader, and lib(s) source tree can be found here.

An experimental x86_64 bootloader that works on both BIOS and UEFI systems. Written in Rust and some inline assembly, buildable on all platforms without additional build-time dependencies (just some rustup components).

Trident is an operating system originally developed as part of a series on Medium and MBP2 before being co-opted into a personal research project.

The springboard bootloader project is a fork of rust-osdev/bootloader fine-tuned to the needs of the Trident 3 project.

As of 2023.11, you will need:

• The Rust nightly as of 2023.11.12, which you may obtain through the official website: https://rust-lang.org/learn/get-started
• Docker to run the build environment: https://www.docker.com/get-started/

Extensions

You will eventually be able to develop your own extensions to Trident 3 through a proposed Extensions API.

Contributing

If you'd like to contribute to this project, please fork it and submit pull requests with your desired features.

1. Fork it.
2. ????? (I forgot what went here)
3. Submit pull request with your feature. ("[FEATURE] describe your feature").
4. Profit?

Useful Links

• MBP2 Page
• Matrix Room
• Discord Server

Requirements

You need a nightly Rust compiler with the llvm-tools-preview component, which can be installed through rustup component add llvm-tools-preview.

Usage

To use this crate, you need to adjust your kernel to be bootable first. Then you can create a bootable disk image from your compiled kernel. These steps are explained in detail below.

If you're already using an older version of the springboard crate or the rust-osdev/bootloader crate, follow our migration guides.

Kernel

To make your kernel compatible with springboard:

• Add a dependency on the springboard_api crate in your kernel's Cargo.toml.
• Your kernel binary should be #![no_std] and #![no_main].
• Define an entry point function with the signature fn kernel_main(boot_info: &'static mut springboard_api::BootInfo) -> !. The function name can be arbitrary.
  • The boot_info argument provides information about available memory, the framebuffer, and more. See the API docs for springboard_api crate for details.
• Use the entry_point macro to register the entry point function: springboard_api::entry_point!(kernel_main);
  • The macro checks the signature of your entry point function and generates a _start entry point symbol for it. (If you use a linker script, make sure that you don't change the entry point name to something else.)
  • To use non-standard configuration, you can pass a second argument of type &'static springboard_api::BootloaderConfig to the entry_point macro. For example, you can require a specific stack size for your kernel:

    const CONFIG: springboard_api::BootloaderConfig = {
        let mut config = springboard_api::BootloaderConfig::new_default();
        config.kernel_stack_size = 100 * 1024; // 100 KiB
        config
    };
    springboard_api::entry_point!(kernel_main, config = &CONFIG);

• Compile your kernel to an ELF executable by running cargo build --target x86_64-unknown-none. You might need to run rustup target add x86_64-unknown-none before to download precompiled versions of the core and alloc crates.
• Thanks to the entry_point macro, the compiled executable contains a special section with metadata and the serialized config, which will enable the springboard crate to load it.

Booting

To combine your kernel with a bootloader and create a bootable disk image, follow these steps:

• Move your full kernel code into a kernel subdirectory.
• Create a new os crate at the top level that defines a workspace.
• Add a build-dependencies on the bootloader crate.
• Create a build.rs build script.
• Set up an artifact dependency to add your kernel crate as a build-dependency:

  # in Cargo.toml
  [build-dependencies]
  kernel = { path = "kernel", artifact = "bin", target = "x86_64-unknown-none" }

  # .cargo/config.toml
  
  [unstable]
  # enable the unstable artifact-dependencies feature, see
  # https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#artifact-dependencies
  bindeps = true

  Alternatively, you can use std::process::Command to invoke the build command of your kernel in the build.rs script.
• Obtain the path to the kernel executable. When using an artifact dependency, you can retrieve this path using std::env::var_os("CARGO_BIN_FILE_MY_KERNEL_my-kernel")
• Use springboard::UefiBoot and/or springboard::BiosBoot to create a bootable disk image with your kernel.
• Do something with the bootable disk images in your main.rs function. For example, run them with QEMU.

See our disk image creation template for a more detailed example.

Architecture

This project is split into three separate entities:

• A springboard_api library with the entry point, configuration, and boot info definitions.
  • Kernels should include this library as a normal cargo dependency.
  • The provided entry_point macro will encode the configuration settings into a separate ELF section of the compiled kernel executable.
• BIOS and UEFI binaries that contain the actual bootloader implementation.
  • The implementations share a higher-level common library.
  • Both implementations load the kernel at runtime from a FAT partition. This FAT partition is created
  • The configuration is read from a special section of the kernel's ELF file, which is created by the entry_point macro of the bootloader_api library.
• A springboard library to create bootable disk images that run a given kernel. This library is the top-level crate in this project.
  • The library builds the BIOS and UEFI implementations in the build.rs.
  • It provides functions to create FAT-formatted bootable disk images, based on the compiled BIOS and UEFI bootloaders.

License

Licensed under Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0).

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.