liveBook · Manning

Semihosting

As explained in Embedded Software with Rust

Semihosting is a development technique in which code on a target device requests services such as text output from a host debugger through a debug connection.

Semihosting lets target firmware request services such as text output from a host debugger over a debug connection. It is useful for early development on bare-metal systems that have no standard output or operating-system logging. section 6.2 section 6.2.1

On Cortex-M, a semihosting call executes BKPT 0xAB. The target pauses while the debugger handles the request and prints on the host, then resumes. The cortex-m-semihosting crate wraps this exchange in the hprintln! macro, allowing formatted output from no_std Rust. section 6.2.1

#![no_std]
#![no_main]

use cortex_m_rt::entry;
use cortex_m_semihosting::hprintln;
use panic_halt as _;

#[entry]
fn main() -> ! {
    hprintln!("Hello from semihosting");
    loop {}
}

A minimal no_std entry point prints one message, then remains in a loop. Add cortex-m-semihosting and the runtime and panic-handler dependencies to the project. section 6.2.1

Enable semihosting in OpenOCD before the firmware makes a call. The command can be passed at startup or issued from GDB as monitor arm semihosting enable. Output appears in the OpenOCD terminal. section 6.2.1 section 6.5.6

openocd -f interface/stlink.cfg -f target/stm32f1x.cfg -c "init; reset init;
 arm semihosting enable"

This OpenOCD startup command initializes an ST-Link-connected STM32 target and enables interception of semihosting traps. section 6.2.1

QEMU can also provide semihosted output before moving to hardware. For the STM32VLDISCOVERY emulation example, select the STM32F100 HAL feature and matching memory map, rebuild, and enable semihosting in the QEMU command. section 2.7.2

qemu-system-arm -machine stm32vldiscovery \
                -cpu cortex-m3 \
                -nographic \
                -semihosting-config enable=on,target=native \
                -kernel target/thumbv7m-none-eabi/release/bluepill-blinky

The QEMU command enables semihosting and runs the built Cortex-M3 firmware without a graphical console. section 2.7.2

Keep the limitations visible:

  • Semihosting blocks the target and adds high latency. Avoid it in timing-sensitive or interrupt-driven paths, and do not use it for profiling output; RTT or direct register access can avoid distorting the measurement. section 6.1.1 section 6.6
  • On Cortex-M0, M0+, and M23, a semihosting breakpoint without an attached debugger escalates to HardFault. The crate's no-semihosting feature can compile the macros out for release builds. section 6.2.1
  • For standalone production diagnostics, UART is an alternative that does not require a probe or active debug session, though it needs peripheral setup. section 6.3.6 section 6.7

Cargo features can separate diagnostic and production behavior. For example, make cortex-m-semihosting and panic-semihosting optional, enable them with a semihosting feature, and use panic-halt by default. Run the diagnostic configuration with cargo run --no-default-features --features semihosting; disabling defaults avoids selecting both panic handlers. section 3.3.2

How Embedded Software with Rust covers it

How deep it goes
Explains breakpoint interception, host configuration, feature selection, and timing and fault risks, with runnable firmware and emulator examples.
Examples
Uses a no_std hprintln! program, OpenOCD commands, a QEMU run, and a feature-selected panic-reporting example.
What you can do after
Apply it via cortex-m-semihosting and OpenOCD or QEMU to obtain development output from firmware.
How it connects
Connects semihosting to breakpoints, HardFault, panic handlers, Cargo features, UART, RTT, and profiling.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Embedded Software with Rust. The section links point to the parts of the book it draws on.