Semihosting

Semihosting is a mechanism that lets embedded devices do I/O on the host and is mainly used to log messages to the host console. Semihosting requires a debug session and pretty much nothing else (no extra wires!) so it’s super convenient to use. The downside is that it’s super slow: each write operation can take several milliseconds depending on the hardware debugger (e.g. ST-Link) you use.

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

  1. #![no_main]
  2. #![no_std]
  4. use panic_halt as _;
  6. use cortex_m_rt::entry;
  7. use cortex_m_semihosting::hprintln;
  9. #[entry]
  10. fn main() -> ! {
  11.     hprintln!("Hello, world!").unwrap();
  13.     loop {}
  14. }

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

  1. $ openocd
  2. (..)
  3. Hello, world!
  4. (..)

You do need to enable semihosting in OpenOCD from GDB first:

  1. (gdb) monitor arm semihosting enable
  2. 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.

  1. $ # this program will block the terminal
  2. $ cargo run
  3.      Running `qemu-system-arm (..)
  4. Hello, world!

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.

  1. #![no_main]
  2. #![no_std]
  4. use panic_halt as _;
  6. use cortex_m_rt::entry;
  7. use cortex_m_semihosting::debug;
  9. #[entry]
  10. fn main() -> ! {
  11.     let roses = "blue";
  13.     if roses == "red" {
  14.         debug::exit(debug::EXIT_SUCCESS);
  15.     } else {
  16.         debug::exit(debug::EXIT_FAILURE);
  17.     }
  19.     loop {}
  20. }
  1. $ cargo run
  2.      Running `qemu-system-arm (..)
  4. $ echo $?
  5. 1

One last tip: you can set the panicking behavior to exit(EXIT_FAILURE). This will let you write no_std run-pass tests that you can run on QEMU.

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.

  1. #![no_main]
  2. #![no_std]
  4. use panic_semihosting as _; // features = ["exit"]
  6. use cortex_m_rt::entry;
  7. use cortex_m_semihosting::debug;
  9. #[entry]
  10. fn main() -> ! {
  11.     let roses = "blue";
  13.     assert_eq!(roses, "red");
  15.     loop {}
  16. }
  1. $ cargo run
  2.      Running `qemu-system-arm (..)
  3. panicked at 'assertion failed: `(left == right)`
  4.   left: `"blue"`,
  5.  right: `"red"`', examples/hello.rs:15:5
  7. $ echo $?
  8. 1

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

  1. panic-semihosting = { version = "VERSION", features = ["exit"] }

where VERSION is the version desired. For more information on dependencies features check the specifying dependencies section of the Cargo book.