adjust docu, rustfmt

Author: 2ndTaleStudio

CHANGELOG.md

@@ -3,7 +3,7 @@
   - ### :bulb: Features
     - add some console log statements in the panic handler that gives a clue of the panic when at least
     the console could be setup properly before panicing the first time :)
-    - use Raspberry Mailbox to retrieve clock speed to initialize miniUart with
+    - use Raspberry Pi Mailbox to retrieve clock speed to initialize miniUart with
   - ### :detective: Fixes
     - Fix the path created by the build script pointing to the linker script file. It should not contain a '\\\\'.
     In addition the examples for the build script to be implementend on consumer side was updated.

Cargo.toml

@@ -39,7 +39,8 @@ ruspiro-interrupt = { path = "../interrupt", version = "0.3" }
 ruspiro_pi3 = [
     "ruspiro-mailbox/ruspiro_pi3",
     "ruspiro-uart/ruspiro_pi3",
-    "ruspiro-timer/ruspiro_pi3"
+    "ruspiro-timer/ruspiro_pi3",
+    "ruspiro-interrupt/ruspiro_pi3"
 ]
 singlecore = []
 with_panic = []

README.md

@@ -8,12 +8,18 @@ This crate provides basic boot code that - when build into a kernel crate - will
 [![License](https://img.shields.io/crates/l/ruspiro-boot.svg)](https://github.com/RusPiRo/ruspiro-boot#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
+-------------------|--------------------------
+``with_panic``     | Implement a default panic handler
+``singlecore``     | Keep all cores except one in a "parked" state so the runtime only uses a single core.
+``ruspiro_pi3``    | This is passed to the dependend crates to ensure they will be build properly for this target device.
+
 ## Usage
 To use this crate simply add the following lines to your ``Cargo.toml`` file:
 (hint: git dependency as long as the crate is not registered at crates.io)
@@ -29,13 +35,6 @@ extern crate ruspiro_boot;
 The usage of `extern crate` is mandatory to ensure the boot strapping is properly linked into the
 final binary.
 
-## Features
-Feature            | Purpose
--------------------|--------------------------
-``with_panic``     | Implement a default panic handler
-``singlecore``     | Keep all cores except one in a "parked" state so the runtime only uses a single core.
-``ruspiro_pi3``    | This is passed to the dependend crates to ensure they will be build properly for this target device.
-
 To successfully build a bare metal binary using this crate for the boot strapping part it is **highly recomended** to use the linker script provided by this crate. Based on the target architecture to be built it is either [link32.ld](link32.ld) or [link64.ld](link64.ld).
 To conviniently refer to the linker scripts 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./link<aarch>.ld``.
 The build script is a simple ``build.rs`` rust file in your project root with the following contents:

build.rs

@@ -43,10 +43,10 @@ fn main() {
                 .compile("excvector");
             // print the linker file location of the boot crate to the env-variables
             println!("cargo:linkerscript={}/link64.ld", script_location.display());
-            
+
             println!("cargo:rerun-if-changed=link64.ld");
             println!("cargo:rerun-if-changed=src/asm/aarch64/bootstrap.S");
             println!("cargo:rerun-if-changed=src/asm/aarch64/exceptionvector.S");
         }
-    }    
+    }
 }

makefile

@@ -14,31 +14,31 @@ all32: export RUSTFLAGS = -C linker=arm-eabi-gcc.exe -C target-cpu=cortex-a53 -C
 all32: export CC = arm-eabi-gcc.exe
 all32: export AR = arm-eabi-ar.exe
 all32: 
-	cargo xbuild --target armv7-unknown-linux-gnueabihf --release --lib --target-dir ./target/ --features ruspiro_pi3
+	cargo xbuild --target armv7-unknown-linux-gnueabihf --release --lib --features ruspiro_pi3
 
 
 all64: export CFLAGS = -march=armv8-a -Wall -O3 -nostdlib -nostartfiles -ffreestanding -mtune=cortex-a53
 all64: export RUSTFLAGS = -C linker=aarch64-elf-gcc.exe -C target-cpu=cortex-a53 -C target-feature=+strict-align,+a53,+fp-armv8,+neon -C link-arg=-nostartfiles -C opt-level=3 -C debuginfo=0 -C link-arg=-T./link64.ld
 all64: export CC = aarch64-elf-gcc.exe
 all64: export AR = aarch64-elf-ar.exe
 all64: 
-	cargo xbuild --target aarch64-unknown-linux-gnu --release --lib --target-dir ./target/ --features ruspiro_pi3
+	cargo xbuild --target aarch64-unknown-linux-gnu --release --lib --features ruspiro_pi3
 
 
 doc: export CFLAGS = -march=armv8-a -Wall -O3 -nostdlib -nostartfiles -ffreestanding -mtune=cortex-a53
 doc: export RUSTFLAGS = -C linker=aarch64-elf-gcc.exe -C target-cpu=cortex-a53 -C target-feature=+strict-align,+a53,+fp-armv8,+neon -C link-arg=-nostartfiles -C opt-level=3 -C debuginfo=0
 doc: export CC = aarch64-elf-gcc.exe
 doc: export AR = aarch64-elf-ar.exe
 doc: 
-	cargo doc --no-deps --target aarch64-unknown-linux-gnu --release --open
+	cargo doc --no-deps --target aarch64-unknown-linux-gnu --features ruspiro_pi3,with_panic --release --open
 
 clippy: export CFLAGS = -march=armv8-a -Wall -O3 -nostdlib -nostartfiles -ffreestanding -mtune=cortex-a53
 clippy: export RUSTFLAGS = -C linker=aarch64-elf-gcc.exe -C target-cpu=cortex-a53 -C target-feature=+strict-align,+a53,+fp-armv8,+neon -C link-arg=-nostartfiles -C opt-level=3 -C debuginfo=0
 clippy: export CC = aarch64-elf-gcc.exe
 clippy: export AR = aarch64-elf-ar.exe
 clippy:
 	# run clippy for this crate using custom target
-	cargo xclippy --target aarch64-unknown-linux-gnu --features ruspiro_pi3
+	cargo xclippy --target aarch64-unknown-linux-gnu --release --features ruspiro_pi3
 
 clean:
 	cargo clean

src/lib.rs

@@ -43,14 +43,17 @@
 //!
 //! # Features
 //!
-//! - `with_panic` will ensure that a default panic handler is implemented.
-//! - `singlecore` enforces the compilation of the single core boot sequence. Only the main core 0 is then running.
-//! - `ruspiro_pi3` is passed to dependent crates to properly build them for the desired Raspberry Pi version
+//! Feature         | Description
+//! ----------------|------------------------------------------------------------------------------
+//! ``ruspiro_pi3`` | Passed to dependent crates to ensure  proper MMIO base memory address for Raspberry Pi 3 when accessing the peripherals
+//! ``singlecore``  | Enforces the compilation of the single core boot sequence. Only the main core 0 is then running.
+//! ``with_panic``  | Compiles a default simple panic handler into the crate. This will hang the core that paniced. No unwinding is performed
 //!
-//! To successfully build a bare metal binary using this crate for the boot strapping part it is
-//! **highly recomended** to use the linker script provided by this crate. Based on the target
-//! architecture to be built it is either [link32.ld](link32.ld) or [link64.ld](link64.ld). To
-//! conviniently refer to the linker scripts contained in this crate it's recommended to use a
+//! ## Hint:
+//! To successfully build a bare metal binary/kernel that depends on this one to perform the boot
+//! strapping part it is **highly recomended** to use the linker script provided by this crate. Based
+//! on the target architecture to be built it is either [link32.ld](link32.ld) or [link64.ld](link64.ld).
+//! To conviniently refer to the linker scripts 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` parameter `-C link-arg=-T./link<aarch>.ld`.
 //! The build script is a simple `build.rs` rust file in your project root with the following
@@ -96,10 +99,10 @@ mod stubs;
 use ruspiro_cache as cache;
 
 use ruspiro_console::*;
+use ruspiro_interrupt::IRQ_MANAGER;
 use ruspiro_mailbox::*;
 use ruspiro_timer as timer;
 use ruspiro_uart::Uart1;
-use ruspiro_interrupt::IRQ_MANAGER;
 
 extern "C" {
     fn __kernel_startup(core: u32);
@@ -141,7 +144,7 @@ fn __rust_entry(core: u32) -> ! {
         // do some arbitrary sleep here to let the uart send the initial greetings before running
         // the kernel, which may initialize the UART for it's own purpose and this would break
         // this transfer...
-        timer::sleep(10000);
+        timer::sleep(timer::Useconds(10000));
 
         // configure interrupt manager for further usage
         IRQ_MANAGER.take_for(|mgr| mgr.initialize());

src/panic.rs

@@ -18,11 +18,16 @@ fn panic(info: &PanicInfo) -> ! {
     // Panicing is undefined behaviour so we are unable to recover from one into a valid state.
     // Halt the panicing core and safely do nothing!
     if let Some(location) = info.location() {
-        ruspiro_console::error!("PANIC at {:?}, {}:{}", location.file(), location.line(), location.column());
+        ruspiro_console::error!(
+            "PANIC at {:?}, {}:{}",
+            location.file(),
+            location.line(),
+            location.column()
+        );
     } else {
         ruspiro_console::error!("PANIC somewhere!");
     }
-    
+
     loop {}
 }