Crate semihosting

Source
Expand description

Semihosting for AArch64, Arm, RISC-V, MIPS32, MIPS64, and Xtensa.

This library provides access to semihosting, a mechanism for programs running on the real or virtual (e.g., QEMU) target to communicate with I/O facilities on the host system. See the Arm documentation for more information on semihosting.

APIs are categorized into the following four types:

  • The top-level API (semihosting::{io,fs,..}) provides a subset of the standard library’s similar APIs.

    • io: Provide no-std io traits and std{in,out,err}. (std{in,out,err} requires stdio feature, others are unconditionally provided)
    • fs: Provide methods to manipulate the contents of the host filesystem. (requires fs feature)
    • process: Provide abort and exit.
    • dbg!/print{,ln}!/eprint{,ln}!: macros to output to stdout/stderr. (requires stdio feature)

    Note that some APIs are not strictly a subset of the standard library.

    • API that uses types not available in core such as Path (technically, the same thing could be implemented, but it makes sense to use CStr directly, because when converting a long Path/OsStr to CStr, it needs to either do an allocation or return an error)
    • API that panics on failure in std (in no-std it makes sense to return Result since panic=abort is default)

  • Helpers that are useful when using this library.

    • c!: CStr literal macro. (Since Rust 1.77, this macro is soft-deprecated in favor of C string literals (c"...").)

  • semihosting::sys module, which provides low-level access to platform-specific semihosting interfaces.

  • semihosting::experimental module, which provides experimental APIs. See optional features for more.

Additionally, this library provides a panic handler for semihosting, -C panic=unwind support, backtrace support, via optional features.

§Platform Support

The following target architectures are supported:

target_archSpecificationsemihosting::sys moduleNote
aarch64Semihosting for AArch32 and AArch64sys::arm_compat
armSemihosting for AArch32 and AArch64sys::arm_compatuse SVC on A+R profile by default based on Arm’s recommendation but it can be changed by trap-hlt feature.
riscv32/riscv64RISC-V Semihostingsys::arm_compat
xtensaOpenOCD Semihostingsys::arm_compatrequires openocd-semihosting feature
mips/mips32r6/mips64/mips64r6Unified Hosting Interface (MD01069)sys::mips

The host must be running an emulator or a debugger attached to the target.

The following targets have been tested on CI. (qemu-system has been tested on Linux, macOS, and Windows hosts, and qemu-user on Linux host.)

targetexitall-apis [1] (system)all-apis [1] (user-mode)panic-unwind (system [2])note
aarch64-unknown-none{,-softfloat}✓✓✓✓
{arm,thumb}v4t-none-eabi✓✓
{arm,thumb}v5te-none-eabi✓✓✓
armv7a-none-eabi{,hf}✓✓✓
armv7r-none-eabi{,hf}✓✓✓
armebv7r-none-eabi{,hf}✓✓
armv8r-none-eabihf✓✓✓
thumbv6m-none-eabi✓✓N/A
thumbv7m-none-eabi✓✓N/A
thumbv7em-none-eabi{,hf}✓✓N/A
thumbv8m.base-none-eabi✓✓N/A
thumbv8m.main-none-eabi{,hf}✓✓N/A
riscv32*-unknown-none-elf✓✓✓✓
riscv64*-unknown-none-elf✓✓✓✓
mips{,el}-unknown-none✓✓N/A[3] [4]
mips64{,el}-unknown-none✓✓N/A[3] [4]
mipsisa32r6{,el}-unknown-none✓✓N/A[3] [4]
mipsisa64r6{,el}-unknown-none✓✓N/A[3] [4]

[1] stdio, fs, time, and args.
[2] I’m not sure how to test panic-unwind on qemu-user.
[3] Requires nightly due to #![feature(asm_experimental_arch)].
[4] It seems unsupported on QEMU 8.0+.

§Optional features

All features are disabled by default.

In general use cases, you probably only need the stdio feature that enables print-related macros and/or the panic-handler feature that exits with a non-zero error code on panic.

[dependencies]
semihosting = { version = "0.1", features = ["stdio", "panic-handler"] }

  • alloc
    Use alloc.

  • stdio
    Enable semihosting::io::{stdin,stdout,stderr} and semihosting::{print*,eprint*,dbg}.

  • fs
    Enable semihosting::fs.

  • panic-handler
    Provide panic handler based on semihosting::process::exit.

    If the stdio feature is also enabled, this attempt to output panic message and location to stderr.

  • trap-hlt
    Arm-specific: Use HLT instruction on A+R profile.

    Arm documentation says:

    The HLT encodings are new in version 2.0 of the semihosting specification. Where possible, have semihosting callers continue to use the previously existing trap instructions to ensure compatibility with legacy semihosting implementations. These trap instructions are HLT for A64, SVC on A+R profile A32 or T32, and BKPT on M profile. However, it is necessary to change from SVC to HLT instructions to support AArch32 semihosting properly in a mixed AArch32/AArch64 system.

    ARM encourages semihosting callers to implement support for trapping using HLT on A32 and T32 as a configurable option. ARM strongly discourages semihosting callers from mixing the HLT and SVC mechanisms within the same executable.

    Based on the Arm’s recommendation, this is implemented as an optional feature.

    Enabling this feature on architectures other than Arm A+R profile will result in a compile error.

  • openocd-semihosting
    Xtensa-specific: Use OpenOCD Semihosting.

    Xtensa has two semihosting interfaces:

    • Tensilica ISS SIMCALL used in Cadence tools and QEMU.
    • Arm-semihosting-compatible semihosting interface used in OpenOCD and probe-rs. (This crate calls it “OpenOCD Semihosting”, which is the same as the option name in newlib-esp32.)

    This crate does not currently support SIMCALL-based semihosting, but users need to explicitly enable the feature to avoid accidentally selecting a different one than one actually want to use.

    Enabling this feature on architectures other than Xtensa will result in a compile error.

  • portable-atomic
    Use portable-atomic’s atomic types.

    portable-atomic provides atomic CAS on targets where the standard library does not provide atomic CAS. To use the panic-unwind feature on such targets (e.g., RISC-V without A-extension), you need to enable this feature.

    See its documentation for details.

  • args
    Enable semihosting::experimental::env::args.

    Note:

    • This feature is experimental (tracking issue: #1) and outside of the normal semver guarantees and minor or patch versions of semihosting may make breaking changes to them at any time.

  • time
    Enable semihosting::experimental::time.

    Note:

    • This feature is experimental (tracking issue: #2) and outside of the normal semver guarantees and minor or patch versions of semihosting may make breaking changes to them at any time.

  • panic-unwind
    Provide -C panic=unwind support for panic handler and enable semihosting::experimental::panic::catch_unwind.

    This currently uses unwinding crate to support unwinding. See its documentation for supported platforms and requirements.

    Note:

    • This feature is experimental (tracking issue: #3) and outside of the normal semver guarantees and minor or patch versions of semihosting may make breaking changes to them at any time.
    • This requires nightly compiler.
    • This implicitly enables the alloc and panic-handler features.
    • This uses atomic CAS. You need to use portable-atomic feature together if your target doesn’t support atomic CAS (e.g., RISC-V without A-extension).
    • When enabling this feature, you may need to rebuild the standard library with -C panic=unwind for catch_unwind to work properly. The recommended way to rebuild the standard library is passing -Z build-std="core,alloc" option to cargo.

  • backtrace
    Provide backtrace support for panic handler.

    This currently uses unwinding crate to support backtrace. See its documentation for supported platforms and requirements.

    Note:

    • This feature is experimental (tracking issue: #3) and outside of the normal semver guarantees and minor or patch versions of semihosting may make breaking changes to them at any time.

    • This requires nightly compiler.

    • This implicitly enables the stdio feature.

    • When enabling this, it is recommended to also enable the panic-unwind feature. Otherwise, a decent backtrace will not be displayed at this time. (Using -C force-unwind-tables may work, but has not been tested yet.)

    • Currently, the backtrace generated is not human-readable.

      panicked at 'a', src/main.rs:86:13
stack backtrace:
  0x84dc0
  0x8ed80
  0x8332c
  0x83654
  0x80644
  0x803cc
  0x809dc
  0x800bc

      You can use addr2line to resolve the addresses and rustfilt to demangle Rust symbols. For example, run the following command (please replace <path/to/binary> with your binary path), then paste the addresses:

      llvm-addr2line -fipe <path/to/binary> | rustfilt

Modules§

experimental
Experimental APIs.
fd
Owned and borrowed Unix-like file descriptors.
fsfs
Host filesystem manipulation operations.
io
Traits, helpers, and type definitions for core I/O functionality.
process
A module for working with processes.
sys
Low-level access to platform-specific semihosting interfaces.

Macros§

c
CStr literal macro.
dbgstdio
eprintstdio
eprintlnstdio
printstdio
printlnstdio