Merge #164

164: Split libtock into core and high level library r=Woyten a=torfmaster

# Summary

In order to address #160 we decided to do a first draft of splitting the library into parts. 

The idea is that there are two layers:
 * libtock-core
 * libtock-rs

(names tbd). Libtock-core contains the panic handler, the entry point, the allocator and the syscall interfaces. libtock-rs uses libtock-core and the interface stays as usual.

# Possible Extensions

We deleted the "blink" code from the panic handler. This saves more than 1kbytes in the text segment. If this feature is still wanted we could implement the following:

 * provide a feature in libtock-core to opt-out  the panic handler in libtock-core
 * provide a feature for libtock-rs to opt-out the panic handler in libtock-core and using a blinking panic handler. 

In the long run the (default) panic handler could exit the app and send debug information to the kernel which could print it for example. This could be implemented once the kernel functionality is in place.

# Open questions

The current implementation of the panic handler more or less silently fails if there is a panic. Panics can be identified by enabling the "trace_syscall" option in the kernel. How should this be tackled?
Should there be a default panic handling or should it be customizable and if yes how should it be customized?

Co-authored-by: Woyten <[email protected]>
Co-authored-by: torfmaster <[email protected]>

Author: 3 people

.gitignore

@@ -1,3 +1,4 @@
 Cargo.lock
 layout.ld
+platform
 target

Cargo.toml

@@ -6,12 +6,14 @@ license = "MIT/Apache-2.0"
 edition = "2018"
 
 [features]
-alloc = [ "linked_list_allocator" ]
+alloc = ["libtock-core/alloc"]
+custom_panic_handler = ["libtock-core/custom_panic_handler"]
+custom_alloc_error_handler = ["libtock-core/custom_alloc_error_handler"]
 
 [dependencies]
 core = { package = "async-support", path = "async-support" }
+libtock-core = { path = "core" }
 libtock_codegen = { path = "codegen" }
-linked_list_allocator = { optional = true, version = "=0.6.5", default-features = false }
 futures = { version = "0.3.1", default-features = false, features = ["unstable", "cfg-target-has-atomic"] }
 
 [dev-dependencies]
@@ -22,22 +24,27 @@ serde = { version = "=1.0.84", default-features = false, features = ["derive"] }
 
 [[example]]
 name = "alloc_error"
-path = "examples-alloc/alloc_error.rs"
-required-features = ["alloc"]
+path = "examples-features/alloc_error.rs"
+required-features = ["alloc", "custom_alloc_error_handler"]
 
 [[example]]
 name = "ble_scanning"
-path = "examples-alloc/ble_scanning.rs"
+path = "examples-features/ble_scanning.rs"
 required-features = ["alloc"]
 
 [[example]]
 name = "libtock_test"
-path = "examples-alloc/libtock_test.rs"
+path = "examples-features/libtock_test.rs"
 required-features = ["alloc"]
 
+[[example]]
+name = "panic"
+path = "examples-features/panic.rs"
+required-features = ["custom_panic_handler"]
+
 [[example]]
 name = "simple_ble"
-path = "examples-alloc/simple_ble.rs"
+path = "examples-features/simple_ble.rs"
 required-features = ["alloc"]
 
 [profile.dev]
@@ -52,4 +59,5 @@ lto = true
 members = [
     "async-support",
     "codegen",
+    "core"
 ]

Makefile

@@ -42,7 +42,9 @@ setup:
 examples:
 	PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples
 	PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples --features=alloc
-	PLATFORM=opentitan cargo build --release --target=riscv32imc-unknown-none-elf --examples
+	PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --example panic --features=custom_panic_handler,custom_alloc_error_handler
+	PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --example alloc_error --features=alloc,custom_alloc_error_handler
+	PLATFORM=opentitan cargo build --release --target=riscv32imc-unknown-none-elf --examples # Important: This is testing a platform without atomics support
 
 .PHONY: test
 test:

core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "libtock-core"
+version = "0.1.0"
+authors = ["Tock Project Developers <[email protected]>"]
+edition = "2018"
+
+[features]
+alloc = [ "linked_list_allocator" ]
+custom_panic_handler = []
+custom_alloc_error_handler = []
+
+[dependencies]
+linked_list_allocator = { optional = true, version = "=0.6.5", default-features = false }

core/README.md

@@ -0,0 +1,33 @@
+# libtock-core
+
+Core crate of `libtock-rs`. It contains the architecture specific code of `libtock-rs`. In particular:
+
+ * the entry point
+ * `panic` and `alloc_error` handlers
+ * the syscalls
+ * the allocator (optional)
+
+It has three important feature flags
+
+ * `alloc` - allow for heap. Enables a linked list allocator.
+ * `custom_panic_handler` - disable the default panic  handler and allow definition of a custom one using `#[panic_handler]`
+ * `custom_alloc_error_handler` - disable the default alloc error handler and allow definition of a custom one using `#[alloc_error_handler]`
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0
+  ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license
+  ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+### Contribution
+
+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
+dual licensed as above, without any additional terms or conditions.
+
+The contribution guidelines are identical to those of `libtock-rs` and can be found here: [contribution guidelines](../CONTRIBUTING.md)

core/src/alloc.rs

@@ -0,0 +1,40 @@
+use core::alloc::GlobalAlloc;
+use core::alloc::Layout;
+use core::ptr;
+use core::ptr::NonNull;
+use linked_list_allocator::Heap;
+
+pub static mut HEAP: Heap = Heap::empty();
+
+struct TockAllocator;
+
+unsafe impl GlobalAlloc for TockAllocator {
+    unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
+        HEAP.allocate_first_fit(layout)
+            .ok()
+            .map_or(ptr::null_mut(), NonNull::as_ptr)
+    }
+
+    unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
+        HEAP.deallocate(NonNull::new_unchecked(ptr), layout)
+    }
+}
+
+#[global_allocator]
+static ALLOCATOR: TockAllocator = TockAllocator;
+
+#[cfg(not(feature = "custom_alloc_error_handler"))]
+#[alloc_error_handler]
+unsafe fn alloc_error_handler(_: Layout) -> ! {
+    use crate::syscalls;
+
+    // Print 0x01 using the LowLevelDebug capsule (if available).
+    let _ = syscalls::command1_insecure(8, 2, 0x01);
+
+    // Signal a panic using the LowLevelDebug capsule (if available).
+    let _ = syscalls::command1_insecure(8, 1, 0x01);
+
+    loop {
+        syscalls::raw::yieldk();
+    }
+}

src/callback.rs renamed to core/src/callback.rs

@@ -0,0 +1,5 @@
+#[cfg_attr(target_arch = "arm", path = "platform_arm.rs")]
+#[cfg_attr(target_arch = "riscv32", path = "platform_riscv32.rs")]
+mod platform;
+
+pub use platform::*;

core/src/debug/mod.rs

@@ -0,0 +1,3 @@
+pub fn get_stack_pointer() -> usize {
+    panic!("No generic implementation.")
+}

core/src/debug/platform.rs

@@ -0,0 +1,5 @@
+pub fn get_stack_pointer() -> usize {
+    let stack_pointer;
+    unsafe { asm!("mov $0, sp" : "=r"(stack_pointer) : : : "volatile") };
+    stack_pointer
+}

core/src/debug/platform_arm.rs

@@ -0,0 +1,5 @@
+pub fn get_stack_pointer() -> usize {
+    let stack_pointer;
+    unsafe { asm!("mv $0, sp" : "=r"(stack_pointer) : : : "volatile") };
+    stack_pointer
+}

core/src/debug/platform_riscv32.rs

@@ -57,10 +57,6 @@ use core::ptr;
 
 #[cfg_attr(target_arch = "riscv32", path = "start_item_riscv32.rs")]
 #[cfg_attr(target_arch = "arm", path = "start_item_arm.rs")]
-#[cfg_attr(
-    not(any(target_arch = "arm", target_arch = "riscv32")),
-    path = "start_item_mock.rs"
-)]
 mod start_item;
 
 /// The header encoded at the beginning of .text by the linker script. It is

src/entry_point/mod.rs renamed to core/src/entry_point/mod.rs

@@ -18,14 +18,7 @@
 //! `rustc_main`. That's covered by the `_start` function in the root of this
 //! crate.
 
-use crate::drivers;
-use crate::leds::LedsDriver;
-use crate::result::TockResult;
-use crate::timer::Duration;
-use crate::timer::ParallelSleepDriver;
-use core::executor;
-use core::panic::PanicInfo;
-use futures::future;
+use crate::syscalls;
 
 #[lang = "start"]
 extern "C" fn start<T>(main: fn() -> T, _argc: isize, _argv: *const *const u8) -> bool
@@ -45,52 +38,25 @@ impl Termination for () {
     fn check_result(self) {}
 }
 
-impl Termination for TockResult<()> {
+impl<S, T> Termination for Result<S, T> {
     fn check_result(self) {
         if self.is_err() {
             unsafe { report_panic() };
         }
     }
 }
 
+#[cfg(not(feature = "custom_panic_handler"))]
 #[panic_handler]
-unsafe fn panic_handler(_info: &PanicInfo) -> ! {
+unsafe fn panic_handler(_info: &core::panic::PanicInfo) -> ! {
     report_panic()
 }
 
 unsafe fn report_panic() -> ! {
     // Signal a panic using the LowLevelDebug capsule (if available).
-    super::debug::low_level_status_code(1);
+    let _ = syscalls::command1_insecure(8, 1, 1);
 
-    // Flash all LEDs (if available).
-    executor::block_on(async {
-        let mut drivers = drivers::retrieve_drivers_unsafe();
-
-        let leds_driver = drivers.leds.init_driver();
-        let mut timer_driver = drivers.timer.create_timer_driver();
-        let timer_driver = timer_driver.activate();
-
-        if let (Ok(leds_driver), Ok(timer_driver)) = (leds_driver, timer_driver) {
-            let _ = blink_all_leds(&leds_driver, &timer_driver).await;
-        } else {
-            future::pending::<()>().await
-        }
-        loop {}
-    })
-}
-
-async fn blink_all_leds(
-    leds_driver: &LedsDriver<'_>,
-    timer_driver: &ParallelSleepDriver<'_>,
-) -> TockResult<()> {
     loop {
-        for led in leds_driver.leds() {
-            led.on()?;
-        }
-        timer_driver.sleep(Duration::from_ms(100)).await?;
-        for led in leds_driver.leds() {
-            led.off()?;
-        }
-        timer_driver.sleep(Duration::from_ms(100)).await?;
+        syscalls::raw::yieldk();
     }
 }

src/entry_point/start_item_mock.rs renamed to core/src/entry_point/start_item.rs

@@ -0,0 +1,17 @@
+#![feature(asm, lang_items, naked_functions)]
+#![cfg_attr(any(target_arch = "arm", target_arch = "riscv32"), no_std)]
+#![cfg_attr(feature = "alloc", feature(alloc_error_handler))]
+
+#[cfg(feature = "alloc")]
+mod alloc;
+mod entry_point;
+#[cfg(any(target_arch = "arm", target_arch = "riscv32"))]
+mod lang_items;
+
+pub mod callback;
+pub mod debug;
+pub mod memop;
+pub mod result;
+pub mod shared_memory;
+pub mod syscalls;
+pub mod unwind_symbols;

src/entry_point/start_item_arm.rs renamed to core/src/entry_point/start_item_arm.rs

@@ -0,0 +1,30 @@
+#[derive(Copy, Clone)]
+pub struct SubscribeError {
+    pub driver_number: usize,
+    pub subscribe_number: usize,
+    pub return_code: isize,
+}
+
+#[derive(Copy, Clone)]
+pub struct CommandError {
+    pub driver_number: usize,
+    pub command_number: usize,
+    pub arg1: usize,
+    pub arg2: usize,
+    pub return_code: isize,
+}
+
+#[derive(Copy, Clone)]
+pub struct AllowError {
+    pub driver_number: usize,
+    pub allow_number: usize,
+    pub return_code: isize,
+}
+
+pub const SUCCESS: isize = 0;
+pub const FAIL: isize = -1;
+pub const EBUSY: isize = -2;
+pub const EALREADY: isize = -3;
+pub const EINVAL: isize = -6;
+pub const ESIZE: isize = -7;
+pub const ENOMEM: isize = -9;

src/entry_point/start_item_riscv32.rs renamed to core/src/entry_point/start_item_riscv32.rs

@@ -1,9 +1,5 @@
 #[cfg_attr(target_arch = "riscv32", path = "platform_riscv32.rs")]
 #[cfg_attr(target_arch = "arm", path = "platform_arm.rs")]
-#[cfg_attr(
-    not(any(target_arch = "arm", target_arch = "riscv32")),
-    path = "platform_mock.rs"
-)]
 mod platform;
 
 use crate::callback::CallbackSubscription;

src/lang_items.rs renamed to core/src/lang_items.rs

@@ -0,0 +1,31 @@
+// Triggers the out-of-memory handler. Should print an error message.
+
+#![no_std]
+#![feature(alloc_error_handler)]
+
+extern crate alloc;
+
+use alloc::vec::Vec;
+use core::alloc::Layout;
+use core::fmt::Write;
+use libtock::result::TockResult;
+use libtock::syscalls;
+
+#[libtock::main]
+fn main() -> TockResult<()> {
+    let mut vec = Vec::new();
+    loop {
+        vec.push(0);
+    }
+}
+
+#[alloc_error_handler]
+unsafe fn alloc_error_handler(_: Layout) -> ! {
+    if let Ok(drivers) = libtock::retrieve_drivers() {
+        let mut console = drivers.console.create_console();
+        let _ = writeln!(console, "alloc_error_handler called");
+    }
+    loop {
+        syscalls::raw::yieldk();
+    }
+}