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
