donglora/vendor/semihosting/src/lib.rs

// SPDX-License-Identifier: Apache-2.0 OR MIT

/*!
<!-- Note: Document from sync-markdown-to-rustdoc:start through sync-markdown-to-rustdoc:end
     is synchronized from README.md. Any changes to that range are not preserved. -->
<!-- tidy:sync-markdown-to-rustdoc:start -->

Semihosting for AArch64, Arm, RISC-V, LoongArch, 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](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst) 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](https://github.com/rust-lang/rust/blob/1.84.0/library/std/src/sys/pal/common/small_c_string.rs#L25-L26) 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 provides low-level access to platform-specific semihosting interfaces.

- `semihosting::experimental` module provides experimental APIs. See [optional features](#optional-features) for more.
  - `env`: Provide `args`.
  - `time`: Provide `Instant` and `SystemTime`.
  - `random`: Provide `fill_bytes` and `fill_uninit_bytes`.
  - `panic`: Provide `catch_unwind`.

Additionally, this library provides a panic handler for semihosting, `-C panic=unwind` support, backtrace support, via [optional features](#optional-features).

## Platform Support

The following target architectures are supported:

| target_arch | Specification | `semihosting::sys` module | Note |
| ----------- | ------------- | ------------------------- | ---- |
| aarch64 | [Semihosting for AArch32 and AArch64](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst) | `sys::arm_compat` | |
| arm | [Semihosting for AArch32 and AArch64](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst) | `sys::arm_compat` | use `SVC` on A+R profile by default based on Arm's recommendation but it can be changed by [`trap-hlt` feature](#optional-features-trap-hlt). |
| riscv32/riscv64 | [RISC-V Semihosting](https://github.com/riscv-non-isa/riscv-semihosting/blob/1.0/riscv-semihosting.adoc) | `sys::arm_compat` | |
| loongarch32/loongarch64 | | `sys::arm_compat` | |
| xtensa | [OpenOCD Semihosting](https://github.com/espressif/openocd-esp32/blob/HEAD/src/target/espressif/esp_xtensa_semihosting.c) | `sys::arm_compat` | requires [`openocd-semihosting` feature](#optional-features-openocd-semihosting) |
| mips/mips32r6/mips64/mips64r6 | Unified 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.)

| target                                    | qemu-system      | qemu-user      | note      |
| ----------------------------------------- | ---------------- | -------------- | --------- |
| `aarch64-unknown-none{,-softfloat}`       | ✓                | ✓              |           |
| `aarch64_be-unknown-none{,-softfloat}`    | ✓                | ✓              | \[2]      |
| `{arm,thumb}v4t-none-eabi`                | ✓                | ✓              |           |
| `{arm,thumb}v5te-none-eabi`               | ✓                | ✓              |           |
| `armv6-none-eabi{,hf}`                    | ✓                | ✓              |           |
| `thumbv6-none-eabi`                       | ✓                | ✓              |           |
| `{arm,thumb}v7a-none-eabi{,hf}`           | ✓                | ✓              |           |
| `{arm,thumb}v7r-none-eabi{,hf}`           | ✓                | ✓              |           |
| `armebv7r-none-eabi{,hf}`                 | *                | ✓              | \[1]      |
| `{arm,thumb}v8r-none-eabihf`              | ✓                | ✓              |           |
| `armebv8r-none-eabihf`                    | *                | ✓              | \[1]      |
| `thumbv6m-none-eabi`                      | ✓                | ✓              |           |
| `thumbv7m-none-eabi`                      | ✓                | ✓              |           |
| `thumbv7em-none-eabi{,hf}`                | ✓                | ✓              |           |
| `thumbv8m.base-none-eabi`                 | ✓                | ✓              |           |
| `thumbv8m.main-none-eabi{,hf}`            | ✓                | ✓              |           |
| `riscv32*-unknown-none-elf`               | ✓                | ✓              |           |
| `riscv64*-unknown-none-elf`               | ✓                | ✓              |           |
| `loongarch32-unknown-none{,-softfloat}`   | ✓                | N/A            | \[2] \[3] |
| `loongarch64-unknown-none{,-softfloat}`   | ✓                | ✓              | \[2]      |
| `mips{,el}-unknown-none`                  | ✓                | N/A            | \[2] \[4] |
| `mips{,el}-mti-none-elf`                  | ✓                | N/A            | \[2] \[4] |
| `mips64{,el}-unknown-none`                | ✓                | N/A            | \[2] \[4] |
| `mipsisa32r6{,el}-unknown-none`           | ✓                | N/A            | \[2] \[4] |
| `mipsisa64r6{,el}-unknown-none`           | ✓                | N/A            | \[2] \[4] |

\[1] Due to [qemu-system bug about big-endian Arm](https://github.com/taiki-e/semihosting/issues/18), operations that contains reading/writing of strings such as file open (`stdio`, `fs`, `random`), `args`, and `SYS_SYSTEM` don't work.<br>
\[2] Tested with patched QEMU ([aarch64_be](https://patchew.org/QEMU/20260106-semihosting-cpu-tswap-v1-0-646576c25f56@eonerc.rwth-aachen.de/), [loongarch](https://lore.kernel.org/qemu-devel/20241222-semihosting-v1-1-8a770df60e9c@flygoat.com/), [mips](https://github.com/taiki-e/qemu/commit/c2d1c8dbc5cb878fbcce824180aa812213785124)). QEMU binaries that we are using for test are available on our QEMU fork ([aarch64_be/mips](https://github.com/taiki-e/qemu/releases/tag/patched-10.2.0), [loongarch](https://github.com/taiki-e/qemu/releases/tag/loongarch-semi-10.1.3)).<br>
\[3] Requires Rust 1.91+.<br>
\[4] Requires nightly due to `#![feature(asm_experimental_arch)]`.<br>

## 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.

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

- **`alloc`**<br>
  Use `alloc`.

- **`stdio`**<br>
  Enable `semihosting::io::{stdin,stdout,stderr}` and `semihosting::{print*,eprint*,dbg}`.

- **`fs`**<br>
  Enable `semihosting::fs`.

- **`panic-handler`**<br>
  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.

- <a name="optional-features-trap-hlt"></a>**`trap-hlt`**<br>
  Arm-specific: Use HLT instruction (except for M-profile architecture).

  [Arm documentation](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst#the-semihosting-interface) 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.

  Note:
  - Enabling this feature on architectures other than Arm or on Arm M-profile architecture will result in a compile error.

- <a name="optional-features-openocd-semihosting"></a>**`openocd-semihosting`**<br>
  Xtensa-specific: Use OpenOCD Semihosting.

  Xtensa has two semihosting interfaces:

  - Tensilica ISS SIMCALL used in Cadence tools and [QEMU](https://www.qemu.org/docs/master/about/emulation.html#supported-targets).
  - Arm-semihosting-compatible semihosting interface used in [OpenOCD](https://github.com/espressif/openocd-esp32/blob/HEAD/src/target/espressif/esp_xtensa_semihosting.c) and [probe-rs](https://github.com/probe-rs/probe-rs/pull/2303). (This crate calls it "OpenOCD Semihosting", which is the same as the option name in [newlib-esp32](https://github.com/espressif/newlib-esp32/blob/esp-4.3.0_20240530/libgloss/xtensa/syscalls.c#L21).)

  When this feature is enabled, this crate uses the latter interface.

  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.

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

- **`portable-atomic`**<br>
  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](https://github.com/taiki-e/portable-atomic#optional-features-critical-section) for details.

- **`args`**<br>
  Enable `semihosting::experimental::env::args`.

  Note:
  - This feature is experimental (tracking issue: [#1](https://github.com/taiki-e/semihosting/issues/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`**<br>
  Enable `semihosting::experimental::time`.

  Note:
  - This feature is experimental (tracking issue: [#2](https://github.com/taiki-e/semihosting/issues/2))
    and outside of the normal semver guarantees and minor or patch versions of semihosting may make
    breaking changes to them at any time.

- **`random`**<br>
  Enable `semihosting::experimental::random`.

  Note:
  - This feature is experimental (tracking issue: [#22](https://github.com/taiki-e/semihosting/issues/22))
    and outside of the normal semver guarantees and minor or patch versions of semihosting may make
    breaking changes to them at any time.
  - This implicitly enables the `fs` features.
  - This is optimized on targets atomic CAS. You may want to use `portable-atomic` feature together if your target doesn't support atomic CAS (e.g., RISC-V without A-extension).

- **`panic-unwind`**<br>
  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](https://github.com/taiki-e/semihosting/issues/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 currently 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`**<br>
  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](https://github.com/taiki-e/semihosting/issues/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 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`](https://doc.rust-lang.org/rustc/codegen-options/index.html#force-unwind-tables) may work, but has not been tested yet.)
  - Currently, the backtrace generated is not human-readable.

    ```text
    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:

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

[portable-atomic]: https://github.com/taiki-e/portable-atomic
[rustfilt]: https://github.com/luser/rustfilt
[unwinding]: https://github.com/nbdd0121/unwinding

<!-- tidy:sync-markdown-to-rustdoc:end -->
*/

#![no_std]
#![doc(test(
    no_crate_inject,
    attr(
        deny(warnings, rust_2018_idioms, single_use_lifetimes),
        allow(dead_code, unused_variables)
    )
))]
#![warn(unsafe_op_in_unsafe_fn)]
#![warn(
    // Lints that may help when writing public library.
    missing_debug_implementations,
    missing_docs,
    clippy::alloc_instead_of_core,
    clippy::exhaustive_enums,
    clippy::exhaustive_structs,
    clippy::impl_trait_in_params,
    clippy::std_instead_of_alloc,
    clippy::std_instead_of_core,
    // clippy::missing_inline_in_public_items,
)]
#![allow(
    clippy::inline_always,
    clippy::len_without_is_empty,
    clippy::missing_panics_doc,
    clippy::must_use_candidate,
    clippy::new_without_default
)]
#![cfg_attr(
    any(
        all(target_arch = "loongarch32", semihosting_no_asm),
        target_arch = "mips",
        target_arch = "mips32r6",
        target_arch = "mips64",
        target_arch = "mips64r6",
        target_arch = "xtensa",
    ),
    feature(asm_experimental_arch)
)]
// docs.rs only (cfg is enabled by docs.rs, not build script)
#![cfg_attr(docsrs, feature(doc_cfg))]
#![cfg_attr(
    docsrs,
    doc(auto_cfg(hide(semihosting_no_duration_checked_float, semihosting_no_error_in_core)))
)]
#![cfg_attr(semihosting_no_strict_provenance, allow(unstable_name_collisions))]

// 64-bit architecture's 32-bit ABI (e.g., AArch64 ILP32 ABI) are also
// unsupported yet (is there a semihosting interface defined for those ABIs?).
#[cfg(not(any(
    all(target_arch = "aarch64", target_pointer_width = "64"),
    target_arch = "arm",
    target_arch = "riscv32",
    all(target_arch = "riscv64", target_pointer_width = "64"),
    target_arch = "loongarch32",
    all(target_arch = "loongarch64", target_pointer_width = "64"),
    target_arch = "mips",
    target_arch = "mips32r6",
    all(target_arch = "mips64", target_pointer_width = "64"),
    all(target_arch = "mips64r6", target_pointer_width = "64"),
    target_arch = "xtensa",
)))]
compile_error!(
    "unsupported target; if you need support for this target, \
     please submit an issue at <https://github.com/taiki-e/semihosting>"
);
#[cfg(target_arch = "xtensa")]
#[cfg(not(feature = "openocd-semihosting"))]
compile_error!(
    "xtensa has two semihosting interfaces so you have to select implementation;\n\
    please enable `openocd-semihosting` feature if you want to use OpenOCD Semihosting used in OpenOCD, probe-rs, etc.\n\
    see <https://docs.rs/semihosting/latest/semihosting/#optional-features-openocd-semihosting> for more."
);
#[cfg(not(target_arch = "xtensa"))]
#[cfg(feature = "openocd-semihosting")]
compile_error!("`openocd-semihosting` feature is only available on Xtensa");
#[cfg(not(all(
    target_arch = "arm",
    not(any(target_feature = "mclass", semihosting_target_feature = "mclass")),
)))]
#[cfg(feature = "trap-hlt")]
compile_error!("`trap-hlt` feature is only available on Arm A+R profile");

#[cfg(feature = "alloc")]
extern crate alloc;
#[cfg(doc)]
extern crate self as semihosting;
#[cfg(test)]
extern crate std;

#[macro_use]
mod utils;

#[cfg(any(
    feature = "panic-unwind",
    all(feature = "random", any(target_has_atomic = "32", feature = "portable-atomic")),
))]
cfg_sel!({
    #[cfg(feature = "portable-atomic")]
    {
        use portable_atomic as atomic;
    }
    #[cfg(else)]
    {
        use core::sync::atomic;
    }
});

#[macro_use]
mod macros;

#[macro_use]
mod c_str;

#[macro_use]
pub mod fd;

#[macro_use]
pub mod io;

#[cfg(any(feature = "args", feature = "panic-unwind", feature = "time", feature = "random"))]
pub mod experimental;
#[cfg(feature = "fs")]
pub mod fs;
#[cfg(feature = "panic-handler")]
mod panicking;
pub mod process;
pub mod sys;

#[cfg(feature = "stdio")]
mod sealed {
    #[allow(unknown_lints, unnameable_types)] // Not public API. unnameable_types is available on Rust 1.79+
    pub trait Sealed {}
}

// Not public API.
#[doc(hidden)]
pub mod __private {
    #[doc(hidden)]
    pub use core::{
        concat,
        ffi::CStr,
        file, line,
        result::Result::{Err, Ok},
        stringify, write, writeln,
    };

    #[doc(hidden)]
    pub use crate::c_str::const_c_str_check;
}