Add debug::exit for tests (#126)

crates/api-desc/CHANGELOG.md

@@ -6,7 +6,7 @@
 
 - Add AES-256-GCM in `crypto::gcm`
 - Add return code to `rng::fill_bytes()`
-- Add `scheduling::breakpoint()`
+- Add `debug::exit()`
 
 ### Patch
 

crates/api-desc/src/debug.rs

@@ -19,19 +19,31 @@ pub(crate) fn new() -> Item {
         /// Debugging operations.
     };
     let name = "debug".into();
-    let items = vec![item! {
-        /// Prints a message to the debug output.
-        ///
-        /// If debug output is disabled then this is a no-op.
-        fn println "dp" {
-            /// The message to print.
+    let items = vec![
+        item! {
+            /// Prints a message to the debug output.
             ///
-            /// Traps if the message is not valid UTF-8.
-            ptr: *const u8,
+            /// If debug output is disabled then this is a no-op.
+            fn println "dp" {
+                /// The message to print.
+                ///
+                /// Traps if the message is not valid UTF-8.
+                ptr: *const u8,
 
-            /// The length of the message in bytes.
-            len: usize,
-        } -> {}
-    }];
+                /// The length of the message in bytes.
+                len: usize,
+            } -> {}
+        },
+        item! {
+            /// Exits the platform with an error code.
+            ///
+            /// This is used by test applets to terminate the platform and propagate the test
+            /// result.
+            fn exit "de" {
+                /// 0 for success, 1 for failure
+                code: usize,
+            } -> {}
+        },
+    ];
     Item::Mod(Mod { docs, name, items })
 }

crates/api-desc/src/scheduling.rs

@@ -31,10 +31,6 @@ pub(crate) fn new() -> Item {
                 count: usize,
             }
         },
-        item! {
-            /// Executes a breakpoint.
-            fn breakpoint "sb" {} -> {}
-        },
     ];
     Item::Mod(Mod { docs, name, items })
 }

crates/board/CHANGELOG.md

@@ -9,7 +9,7 @@
 ### Minor
 
 - Add AES-256-GCM support
-- Add breakpoint in Api
+- Add `debug::exit()`
 
 ### Patch
 

crates/board/src/debug.rs

@@ -0,0 +1,27 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//! Debugging and testing interface.
+
+/// Debugging and testing interface.
+pub trait Api {
+    /// Exits the platform with a success/failure result.
+    fn exit(&mut self, success: bool) -> !;
+}
+
+impl Api for ! {
+    fn exit(&mut self, _: bool) -> ! {
+        unreachable!()
+    }
+}

crates/board/src/lib.rs

@@ -26,6 +26,7 @@ use wasefire_store as store;
 
 pub mod button;
 pub mod crypto;
+pub mod debug;
 pub mod led;
 pub mod rng;
 pub mod timer;
@@ -49,9 +50,6 @@ pub trait Api {
     /// available, this function blocks and enters a power-saving state until an event triggers.
     fn wait_event(&mut self) -> Event;
 
-    /// Executes a breakpoint.
-    fn breakpoint(&mut self);
-
     /// Storage type.
     type Storage: store::Storage;
 
@@ -68,6 +66,10 @@ pub trait Api {
     where Self: 'a;
     fn crypto(&mut self) -> Self::Crypto<'_>;
 
+    type Debug<'a>: debug::Api
+    where Self: 'a;
+    fn debug(&mut self) -> Self::Debug<'_>;
+
     type Led<'a>: led::Api
     where Self: 'a;
     fn led(&mut self) -> Self::Led<'_>;
@@ -132,10 +134,6 @@ mod tests {
                 todo!()
             }
 
-            fn breakpoint(&mut self) {
-                todo!()
-            }
-
             type Storage = !;
             fn take_storage(&mut self) -> Option<Self::Storage> {
                 todo!()
@@ -151,6 +149,11 @@ mod tests {
                 todo!()
             }
 
+            type Debug<'a> = !;
+            fn debug(&mut self) -> Self::Debug<'_> {
+                todo!()
+            }
+
             type Led<'a> = ();
             fn led(&mut self) -> Self::Led<'_> {
                 ()

crates/prelude/CHANGELOG.md

@@ -6,7 +6,7 @@
 
 - Add AES-256-GCM in `crypto::gcm`
 - Add return code to `rng::fill_bytes()`
-- Add `scheduling::breakpoint()`
+- Add `debug::exit()` and `debug::assert*()`
 
 ## 0.1.3
 

crates/prelude/src/debug.rs

@@ -53,3 +53,28 @@ macro_rules! debug {
         }
     };
 }
+
+/// Exits the platform indicating success of failure.
+pub fn exit(success: bool) -> ! {
+    let params = api::exit::Params { code: if success { 0 } else { 1 } };
+    unsafe { api::exit(params) };
+    unreachable!()
+}
+
+/// Asserts that a condition holds and exits with an error otherwise.
+#[track_caller]
+pub fn assert(condition: bool) {
+    if !condition {
+        debug!("Assertion failed at {}", core::panic::Location::caller());
+        exit(false);
+    }
+}
+
+/// Asserts that an equality holds and exits with an error otherwise.
+#[track_caller]
+pub fn assert_eq<T: ?Sized + Eq + core::fmt::Debug>(x: &T, y: &T) {
+    if x != y {
+        debug!("{x:?} != {y:?} at {}", core::panic::Location::caller());
+        exit(false);
+    }
+}

crates/prelude/src/scheduling.rs

@@ -46,8 +46,3 @@ pub fn wait_indefinitely() -> ! {
         wait_for_callback();
     }
 }
-
-/// Executes a breakpoint.
-pub fn breakpoint() {
-    unsafe { api::breakpoint() };
-}

crates/runner-host/src/board.rs

@@ -14,6 +14,7 @@
 
 pub mod button;
 mod crypto;
+mod debug;
 mod led;
 mod rng;
 pub mod timer;
@@ -52,10 +53,6 @@ impl Api for Board {
         self.receiver.blocking_recv().unwrap()
     }
 
-    fn breakpoint(&mut self) {
-        unsafe { std::intrinsics::breakpoint() };
-    }
-
     type Storage = FileStorage;
     fn take_storage(&mut self) -> Option<Self::Storage> {
         self.state.lock().unwrap().storage.take()
@@ -71,6 +68,11 @@ impl Api for Board {
         self
     }
 
+    type Debug<'a> = &'a mut Self;
+    fn debug(&mut self) -> Self::Debug<'_> {
+        self
+    }
+
     type Led<'a> = &'a mut Self;
     fn led(&mut self) -> Self::Led<'_> {
         self

crates/runner-host/src/board/debug.rs

@@ -0,0 +1,23 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use wasefire_board_api as board;
+
+use crate::board::Board;
+
+impl board::debug::Api for &mut Board {
+    fn exit(&mut self, success: bool) -> ! {
+        std::process::exit(if success { 0 } else { 1 })
+    }
+}

crates/runner-nordic/src/tasks.rs

@@ -20,6 +20,7 @@ use crate::Board;
 pub mod button;
 pub mod clock;
 mod crypto;
+mod debug;
 mod led;
 mod rng;
 pub mod usb;
@@ -44,10 +45,6 @@ impl board::Api for Board {
         }
     }
 
-    fn breakpoint(&mut self) {
-        cortex_m::asm::bkpt();
-    }
-
     type Storage = crate::storage::Storage;
     fn take_storage(&mut self) -> Option<Self::Storage> {
         critical_section::with(|cs| self.0.borrow_ref_mut(cs).storage.take())
@@ -63,6 +60,11 @@ impl board::Api for Board {
         self
     }
 
+    type Debug<'a> = &'a mut Self;
+    fn debug(&mut self) -> Self::Debug<'_> {
+        self
+    }
+
     type Led<'a> = &'a mut Self;
     fn led(&mut self) -> Self::Led<'_> {
         self

crates/runner-nordic/src/tasks/debug.rs

@@ -0,0 +1,32 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use wasefire_board_api as board;
+
+use crate::tasks::Board;
+
+impl board::debug::Api for &mut Board {
+    fn exit(&mut self, success: bool) -> ! {
+        if success {
+            loop {
+                cortex_m::asm::bkpt();
+            }
+        } else {
+            #[cfg(feature = "debug")]
+            panic_probe::hard_fault();
+            #[cfg(feature = "release")]
+            panic!();
+        }
+    }
+}

crates/scheduler/CHANGELOG.md

@@ -7,7 +7,7 @@
 - Add AES-256-GCM support
 - Support `rng::fill_bytes()` return code
 - Add `Events::is_empty()`
-- Support `scheduling::breakpoint()`
+- Support `debug::exit()`
 
 ### Patch
 

crates/scheduler/src/call/debug.rs

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 use wasefire_applet_api::debug::{self as api, Api};
+use wasefire_board_api::debug::Api as _;
 use wasefire_board_api::Api as Board;
 use wasefire_logger as logger;
 
@@ -21,6 +22,7 @@ use crate::{DispatchSchedulerCall, SchedulerCall, Trap};
 pub fn process<B: Board>(call: Api<DispatchSchedulerCall<B>>) {
     match call {
         Api::Println(call) => println(call),
+        Api::Exit(call) => exit(call),
     }
 }
 
@@ -33,3 +35,8 @@ fn println<B: Board>(mut call: SchedulerCall<B, api::println::Sig>) {
     };
     call.reply(results)
 }
+
+fn exit<B: Board>(mut call: SchedulerCall<B, api::exit::Sig>) {
+    let api::exit::Params { code } = call.read();
+    call.scheduler().board.debug().exit(*code == 0);
+}

crates/scheduler/src/call/scheduling.rs

@@ -21,7 +21,6 @@ pub fn process<B: Board>(call: Api<DispatchSchedulerCall<B>>) {
     match call {
         Api::WaitForCallback(call) => wait_for_callback(call),
         Api::NumPendingCallbacks(call) => num_pending_callbacks(call),
-        Api::Breakpoint(call) => breakpoint(call),
     }
 }
 
@@ -37,9 +36,3 @@ fn num_pending_callbacks<B: Board>(mut call: SchedulerCall<B, api::num_pending_c
     let count = (call.applet().len() as u32).into();
     call.reply(Ok(api::num_pending_callbacks::Results { count }));
 }
-
-fn breakpoint<B: Board>(mut call: SchedulerCall<B, api::breakpoint::Sig>) {
-    let api::breakpoint::Params {} = call.read();
-    call.scheduler().board.breakpoint();
-    call.reply(Ok(api::breakpoint::Results {}));
-}

examples/assemblyscript/api.ts

@@ -258,6 +258,16 @@
     // The length of the message in bytes.
     len: usize,
   ): void
+
+  // Exits the platform with an error code.
+  //
+  // This is used by test applets to terminate the platform and propagate the test
+  // result.
+  @external("env", "de")
+  export declare function debug_exit(
+    // 0 for success, 1 for failure
+    code: usize,
+  ): void
 // END OF MODULE debug
 
 // START OF MODULE led
@@ -325,11 +335,6 @@
   export declare function scheduling_num_pending_callbacks(
   // How many callbacks are pending.
   ): usize
-
-  // Executes a breakpoint.
-  @external("env", "sb")
-  export declare function scheduling_breakpoint(
-  ): void
 // END OF MODULE scheduling
 
 // START OF MODULE store