Merge pull request #3 from pftbest/exit

Add `exit` and `report_exception` syscalls.

src/debug.rs

@@ -0,0 +1,96 @@
+//! Interacting with debugging agent
+//!
+//! # Example
+//!
+//! This example will show how to terminate the QEMU session. The program
+//! should be running under QEMU with semihosting enabled
+//! (use `-semihosting` flag).
+//!
+//! Target program:
+//!
+//! ```
+//! #[macro_use]
+//! extern crate cortex_m_semihosting;
+//! use cortex_m_semihosting::debug::{self, EXIT_SUCCESS, EXIT_FAILURE};
+//!
+//! fn main() {
+//!     if 2 == 2 {
+//!         // report success
+//!         debug::exit(EXIT_SUCCESS);
+//!     } else {
+//!         // report failure
+//!         debug::exit(EXIT_FAILURE);
+//!     }
+//! }
+//!
+
+/// This values are taken from section 5.5.2 of
+/// ADS Debug Target Guide (DUI0058).
+pub enum Exception {
+    // Hardware reason codes
+    BranchThroughZero = 0x20000,
+    UndefinedInstr = 0x20001,
+    SoftwareInterrupt = 0x20002,
+    PrefetchAbort = 0x20003,
+    DataAbort = 0x20004,
+    AddressException = 0x20005,
+    IRQ = 0x20006,
+    FIQ = 0x20007,
+    // Software reason codes
+    BreakPoint = 0x20020,
+    WatchPoint = 0x20021,
+    StepComplete = 0x20022,
+    RunTimeErrorUnknown = 0x20023,
+    InternalError = 0x20024,
+    UserInterruption = 0x20025,
+    ApplicationExit = 0x20026,
+    StackOverflow = 0x20027,
+    DivisionByZero = 0x20028,
+    OSSpecific = 0x20029,
+}
+
+/// Status enum for `exit` syscall.
+pub type ExitStatus = Result<(), ()>;
+
+/// Successful execution of a program.
+pub const EXIT_SUCCESS: ExitStatus = Ok(());
+
+/// Unsuccessful execution of a program.
+pub const EXIT_FAILURE: ExitStatus = Err(());
+
+/// Reports to the debugger that the execution has completed.
+///
+/// This call can be used to terminate QEMU session and report back success
+/// or failure. If you need to pass more than one type of error, consider
+/// using `report_exception` syscall instead.
+///
+/// This call should not return. However, it is possible for the debugger
+/// to request that the application continue. In that case this call
+/// returns normally.
+///
+pub fn exit(status: ExitStatus) {
+    match status {
+        EXIT_SUCCESS => report_exception(Exception::ApplicationExit),
+        EXIT_FAILURE => report_exception(Exception::RunTimeErrorUnknown),
+    }
+}
+
+/// Report an exception to the debugger directly.
+///
+/// Exception handlers can use this SWI at the end of handler chains
+/// as the default action, to indicate that the exception has not been handled.
+///
+/// This call should not return. However, it is possible for the debugger
+/// to request that the application continue. In that case this call
+/// returns normally.
+///
+/// # Arguments
+///
+/// * `reason` - A reason code reported back to the debugger.
+///
+pub fn report_exception(reason: Exception) {
+    let code = reason as usize;
+    unsafe {
+        syscall1!(REPORT_EXCEPTION, code);
+    }
+}

src/lib.rs

@@ -29,6 +29,9 @@
 //! Target program:
 //!
 //! ```
+//! #[macro_use]
+//! extern crate cortex_m_semihosting;
+//!
 //! fn main() {
 //!     // File descriptor (on the host)
 //!     const STDOUT: usize = 1;
@@ -110,8 +113,9 @@ mod macros;
 
 pub mod io;
 pub mod nr;
+pub mod debug;
 
-/// Performs a semihosting operation
+/// Performs a semihosting operation, takes a pointer to an argument block
 #[inline(always)]
 #[cfg(target_arch = "arm")]
 pub unsafe fn syscall<T>(mut nr: usize, arg: &T) -> usize {
@@ -123,7 +127,26 @@ pub unsafe fn syscall<T>(mut nr: usize, arg: &T) -> usize {
     nr
 }
 
+/// Performs a semihosting operation, takes a pointer to an argument block
 #[cfg(not(target_arch = "arm"))]
 pub unsafe fn syscall<T>(_nr: usize, _arg: &T) -> usize {
     0
 }
+
+/// Performs a semihosting operation, takes one integer as an argument
+#[inline(always)]
+#[cfg(target_arch = "arm")]
+pub unsafe fn syscall1(mut nr: usize, arg: usize) -> usize {
+    asm!("bkpt 0xAB"
+         : "+{r0}"(nr)
+         : "{r1}"(arg)
+         : "memory"
+         : "volatile");
+    nr
+}
+
+/// Performs a semihosting operation, takes one integer as an argument
+#[cfg(not(target_arch = "arm"))]
+pub unsafe fn syscall1(_nr: usize, _arg: usize) -> usize {
+    0
+}

src/macros.rs

@@ -1,8 +1,11 @@
 /// Variable argument version of `syscall`
 #[macro_export]
 macro_rules! syscall {
-    ($nr:ident, $a1:expr, $a2:expr) => {
-        $crate::syscall($crate::nr::$nr, &($a1 as usize))
+    ($nr:ident) => {
+        $crate::syscall1($crate::nr::$nr, 0)
+    };
+    ($nr:ident, $a1:expr) => {
+        $crate::syscall($crate::nr::$nr, &[$a1 as usize])
     };
     ($nr:ident, $a1:expr, $a2:expr) => {
         $crate::syscall($crate::nr::$nr, &[$a1 as usize, $a2 as usize])
@@ -17,6 +20,14 @@ macro_rules! syscall {
     };
 }
 
+/// Macro version of `syscall1`
+#[macro_export]
+macro_rules! syscall1 {
+    ($nr:ident, $a1:expr) => {
+        $crate::syscall1($crate::nr::$nr, $a1 as usize)
+    };
+}
+
 /// Macro for printing to the **host's** standard stderr
 #[macro_export]
 macro_rules! ehprint {

src/nr.rs

@@ -22,3 +22,5 @@ pub const TMPNAM: usize = 0x0d;
 pub const WRITE0: usize = 0x04;
 pub const WRITE: usize = 0x05;
 pub const WRITEC: usize = 0x03;
+pub const ENTER_SVC: usize = 0x17;
+pub const REPORT_EXCEPTION: usize = 0x18;