ruspiro-boot

Crates.ioruspiro-boot
lib.rsruspiro-boot
version0.5.4
sourcesrc
created_at2019-07-29 17:07:39.911303
updated_at2021-12-29 11:03:50.720215
descriptionBare metal boot strapper code for the Raspberry Pi 3 to conviniently start a custom kernel within the Rust environment without the need to deal with all the initial setup like stack pointers, switch to the appropriate exeption level and getting all cores kicked off for processing of code compiled from Rust.
homepage
repositoryhttps://github.com/RusPiRo/ruspiro-boot/tree/v0.5.4
max_upload_size
id152680
size69,940
(2ndTaleStudio)

documentation

https://docs.rs/ruspiro-boot/0.5.4

README

Boot crate for the RusPiRo kernel

This crate provides basic boot code that - when build into a kernel crate - will be executed as soon as the Raspberry Pi powers up. Building and finally linking this crate into the kernel image depends on several linker symbols to be present. Therfore, it is recommended to use the linker script provided when bulding the kernel.

CI Latest Version Documentation License

Hint

The usage of this crate does only make sense when building a Raspberry Pi 3 bare metal kernel. The baremetal bootstrapping provided by this crate can be build for either Aarch32 or Aarch64 target architectures. It has been verified to cross compile from a Windows host machine successfully for both architectures and the execution is tested on a Raspberry Pi 3 B+.

Features

Feature Purpose

multicore | Compiles the multi-core version of the crate, kicking off all 4 cores of the Raspberry Pi. panic | Enable the default panic handler. This feature is enabled by default.

Usage

To use this crate simply add the following lines to your Cargo.toml file:

[dependencies]
ruspiro-boot = "0.5.4"

In the main rust file refer to this crate with this:

#[macro_use]
extern crate ruspiro_boot;

The usage of extern crate is mandatory to ensure the boot strapping is properly linked into the final binary.

To successfully build a bare metal binary using this crate for the boot strapping part it is highly recomended to use the linker script link64.ld provided by this crate. To conviniently refer to the linker script contained in this crate it's recommended to use a specific build script in your project that copies the required file to your current project folder and could then be referred to with the RUSTFLAG -C link-arg=-T./link64.ld. The build script is a simple build.rs rust file in your project root with the following contents:

use std::{env, fs, path::Path};

fn main() {
    // copy the linker script from the boot crate to the current directory
    // so it will be invoked by the linker
    let ld_source = env::var_os("DEP_RUSPIRO_BOOT_LINKERSCRIPT")
        .expect("error in ruspiro build, `ruspiro-boot` not a dependency?")
        .to_str()
        .unwrap()
        .replace("\\", "/");
    let src_file = Path::new(&ld_source);
    let trg_file = format!(
        "{}/{}",
        env::current_dir().unwrap().display(),
        src_file.file_name().unwrap().to_str().unwrap()
    );
    println!("Copy linker script from {:?}, to {:?}", src_file, trg_file);
    fs::copy(src_file, trg_file).unwrap();
}

To get started you may want to check out the template projects provided here

License

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

Commit count: 0

cargo fmt