Semihosting

The crate provides an API to do semihosting operations on Cortex-M devices. The program below is the semihosting version of “Hello, world!”:

If you run this program on hardware you’ll see the “Hello, world!” message within the OpenOCD logs.

(..)
Hello, world!
(..)

(gdb) monitor arm semihosting enable
semihosting is enabled

QEMU understands semihosting operations so the above program will also work with qemu-system-arm without having to start a debug session. Note that you’ll need to pass the -semihosting-config flag to QEMU to enable semihosting support; these flags are already included in the .cargo/config.toml file of the template.

There’s also an exit semihosting operation that can be used to terminate the QEMU process. Important: do not use debug::exit on hardware; this function can corrupt your OpenOCD session and you will not be able to debug more programs until you restart it.

#![no_main]
#![no_std]
use panic_halt as _;
use cortex_m_rt::entry;
#[entry]
fn main() -> ! {
    let roses = "blue";
    if roses == "red" {
        debug::exit(debug::EXIT_SUCCESS);
    } else {
        debug::exit(debug::EXIT_FAILURE);
    }
    loop {}

$ cargo run
     Running `qemu-system-arm (..)
1

For convenience, the panic-semihosting crate has an “exit” feature that when enabled invokes exit(EXIT_FAILURE) after logging the panic message to the host stderr.

$ cargo run
     Running `qemu-system-arm (..)
panicked at 'assertion failed: `(left == right)`
  left: `"blue"`,
 right: `"red"`', examples/hello.rs:15:5
$ echo $?

NOTE: To enable this feature on panic-semihosting, edit your Cargo.toml dependencies section where panic-semihosting is specified with: