{"id":15994675,"url":"https://github.com/taiki-e/semihosting","last_synced_at":"2026-01-12T13:39:28.673Z","repository":{"id":145402689,"uuid":"615978969","full_name":"taiki-e/semihosting","owner":"taiki-e","description":"Semihosting for AArch64, ARM, RISC-V, MIPS32, MIPS64, and Xtensa.","archived":false,"fork":false,"pushed_at":"2025-12-19T19:13:40.000Z","size":447,"stargazers_count":16,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-22T08:27:08.830Z","etag":null,"topics":["no-std","qemu","rust"],"latest_commit_sha":null,"homepage":"https://docs.rs/semihosting","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taiki-e.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"taiki-e"}},"created_at":"2023-03-19T08:58:13.000Z","updated_at":"2025-12-21T12:46:12.000Z","dependencies_parsed_at":"2026-01-06T05:06:06.068Z","dependency_job_id":null,"html_url":"https://github.com/taiki-e/semihosting","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/taiki-e/semihosting","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taiki-e%2Fsemihosting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taiki-e%2Fsemihosting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taiki-e%2Fsemihosting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taiki-e%2Fsemihosting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taiki-e","download_url":"https://codeload.github.com/taiki-e/semihosting/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taiki-e%2Fsemihosting/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28339305,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["no-std","qemu","rust"],"created_at":"2024-10-08T07:09:45.931Z","updated_at":"2026-01-12T13:39:28.641Z","avatar_url":"https://github.com/taiki-e.png","language":"Rust","funding_links":["https://github.com/sponsors/taiki-e"],"categories":[],"sub_categories":[],"readme":"# semihosting\n\n[![crates.io](https://img.shields.io/crates/v/semihosting?style=flat-square\u0026logo=rust)](https://crates.io/crates/semihosting)\n[![docs.rs](https://img.shields.io/badge/docs.rs-semihosting-blue?style=flat-square\u0026logo=docs.rs)](https://docs.rs/semihosting)\n[![license](https://img.shields.io/badge/license-Apache--2.0_OR_MIT-blue?style=flat-square)](#license)\n[![msrv](https://img.shields.io/badge/msrv-1.64-blue?style=flat-square\u0026logo=rust)](https://www.rust-lang.org)\n[![github actions](https://img.shields.io/github/actions/workflow/status/taiki-e/semihosting/ci.yml?branch=main\u0026style=flat-square\u0026logo=github)](https://github.com/taiki-e/semihosting/actions)\n\n\u003c!-- tidy:sync-markdown-to-rustdoc:start:src/lib.rs --\u003e\n\nSemihosting for AArch64, Arm, RISC-V, MIPS32, MIPS64, and Xtensa.\n\nThis 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.\n\nAPIs are categorized into the following four types:\n\n- The top-level API (`semihosting::{io,fs,..}`) provides a subset of the standard library's similar APIs.\n  - `io`: Provide no-std io traits and `std{in,out,err}`. (`std{in,out,err}` requires `stdio` feature, others are unconditionally provided)\n  - `fs`: Provide methods to manipulate the contents of the host filesystem. (requires `fs` feature)\n  - `process`: Provide `abort` and `exit`.\n  - `dbg!`/`print{,ln}!`/`eprint{,ln}!`: macros to output to stdout/stderr. (requires `stdio` feature)\n\n  Note that some APIs are not strictly a subset of the standard library.\n  - 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)\n  - API that panics on failure in `std` (in no-std it makes sense to return `Result` since `panic=abort` is default)\n\n- Helpers that are useful when using this library.\n  - `c!`: `CStr` literal macro. (Since Rust 1.77, this macro is soft-deprecated in favor of C string literals (`c\"...\"`).)\n\n- `semihosting::sys` module provides low-level access to platform-specific semihosting interfaces.\n\n- `semihosting::experimental` module provides experimental APIs. See [optional features](#optional-features) for more.\n  - `env`: Provide `args`.\n  - `time`: Provide `Instant` and `SystemTime`.\n  - `random`: Provide `fill_bytes` and `fill_uninit_bytes`.\n  - `panic`: Provide `catch_unwind`.\n\nAdditionally, this library provides a panic handler for semihosting, `-C panic=unwind` support, backtrace support, via [optional features](#optional-features).\n\n## Platform Support\n\nThe following target architectures are supported:\n\n| target_arch | Specification | `semihosting::sys` module | Note |\n| ----------- | ------------- | ------------------------- | ---- |\n| aarch64 | [Semihosting for AArch32 and AArch64](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst) | `sys::arm_compat` | |\n| 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). |\n| riscv32/riscv64 | [RISC-V Semihosting](https://github.com/riscv-non-isa/riscv-semihosting/blob/1.0/riscv-semihosting.adoc) | `sys::arm_compat` | |\n| 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) |\n| mips/mips32r6/mips64/mips64r6 | Unified Hosting Interface (MD01069) | `sys::mips` | |\n\nThe host must be running an emulator or a debugger attached to the target.\n\nThe following targets have been tested on CI. (qemu-system has been tested on Linux, macOS, and Windows hosts, and qemu-user on Linux host.)\n\n| target                                    | exit | all-apis \\[1] (system) | all-apis \\[1] (user-mode) | panic-unwind (system \\[2]) | note      |\n| ----------------------------------------- | ---- | ---------------------- | ------------------------- | -------------------------- | --------- |\n| `aarch64-unknown-none{,-softfloat}`       | ✓    | ✓                      | ✓                         | ✓                          |           |\n| `aarch64_be-unknown-none{,-softfloat}`    | ✓    |                        | ✓                         | ✓                          | \\[3]      |\n| `{arm,thumb}v4t-none-eabi`                | ✓    | ✓                      | ✓                         |                            |           |\n| `{arm,thumb}v5te-none-eabi`               | ✓    | ✓                      | ✓                         |                            |           |\n| `{arm,thumb}v6-none-eabi{,hf}`            | ✓    | ✓                      | ✓                         |                            |           |\n| `{arm,thumb}v7a-none-eabi{,hf}`           | ✓    | ✓                      | ✓                         |                            |           |\n| `{arm,thumb}v7r-none-eabi{,hf}`           | ✓    | ✓                      | ✓                         |                            |           |\n| `armebv7r-none-eabi{,hf}`                 | ✓    |                        | ✓                         |                            | \\[3]      |\n| `{arm,thumb}v8r-none-eabihf`              | ✓    | ✓                      | ✓                         |                            |           |\n| `armebv8r-none-eabihf`                    | ✓    |                        | ✓                         |                            | \\[3]      |\n| `thumbv6m-none-eabi`                      | ✓    | ✓                      | ✓                         |                            |           |\n| `thumbv7m-none-eabi`                      | ✓    | ✓                      | ✓                         |                            |           |\n| `thumbv7em-none-eabi{,hf}`                | ✓    | ✓                      | ✓                         |                            |           |\n| `thumbv8m.base-none-eabi`                 | ✓    | ✓                      | ✓                         |                            |           |\n| `thumbv8m.main-none-eabi{,hf}`            | ✓    | ✓                      | ✓                         |                            |           |\n| `riscv32*-unknown-none-elf`               | ✓    | ✓                      | ✓                         | ✓                          |           |\n| `riscv64*-unknown-none-elf`               | ✓    | ✓                      | ✓                         | ✓                          |           |\n| `mips{,el}-unknown-none`                  | ✓    | ✓                      | N/A                       |                            | \\[4] \\[5] |\n| `mips{,el}-mti-none-elf`                  | ✓    | ✓                      | N/A                       |                            | \\[4] \\[5] |\n| `mips64{,el}-unknown-none`                | ✓    | ✓                      | N/A                       |                            | \\[4] \\[5] |\n| `mipsisa32r6{,el}-unknown-none`           | ✓    | ✓                      | N/A                       |                            | \\[4] \\[5] |\n| `mipsisa64r6{,el}-unknown-none`           | ✓    | ✓                      | N/A                       |                            | \\[4] \\[5] |\n\n\\[1] `stdio`, `fs`, `time`, and `args`.\u003cbr\u003e\n\\[2] I'm not sure how to test panic-unwind on qemu-user.\u003cbr\u003e\n\\[3] QEMU's big-endian Arm/AArch64 support in [broken on system mode](https://github.com/taiki-e/semihosting/issues/18).\u003cbr\u003e\n\\[4] Requires nightly due to `#![feature(asm_experimental_arch)]`.\u003cbr\u003e\n\\[5] It seems [unsupported on QEMU 8.0+](https://qemu-project.gitlab.io/qemu/about/removed-features.html#mips-trap-and-emulate-kvm-support-removed-in-8-0).\u003cbr\u003e\n\n## Optional features\n\nAll features are disabled by default.\n\nIn 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.\n\n```toml\n[dependencies]\nsemihosting = { version = \"0.1\", features = [\"stdio\", \"panic-handler\"] }\n```\n\n- **`alloc`**\u003cbr\u003e\n  Use `alloc`.\n\n- **`stdio`**\u003cbr\u003e\n  Enable `semihosting::io::{stdin,stdout,stderr}` and `semihosting::{print*,eprint*,dbg}`.\n\n- **`fs`**\u003cbr\u003e\n  Enable `semihosting::fs`.\n\n- **`panic-handler`**\u003cbr\u003e\n  Provide panic handler based on `semihosting::process::exit`.\n\n  If the `stdio` feature is also enabled, this attempt to output panic message and\n  location to stderr.\n\n- \u003ca name=\"optional-features-trap-hlt\"\u003e\u003c/a\u003e**`trap-hlt`**\u003cbr\u003e\n  Arm-specific: Use HLT instruction (except for M-profile architecture).\n\n  [Arm documentation](https://github.com/ARM-software/abi-aa/blob/2025Q1/semihosting/semihosting.rst#the-semihosting-interface) says:\n\n  \u003e The `HLT` encodings are new in version 2.0 of the semihosting specification.\n  \u003e Where possible, have semihosting callers continue to use the previously existing\n  \u003e trap instructions to ensure compatibility with legacy semihosting implementations.\n  \u003e These trap instructions are `HLT` for A64, `SVC` on A+R profile A32 or T32, and\n  \u003e `BKPT` on M profile. However, it is necessary to change from SVC to HLT instructions\n  \u003e to support AArch32 semihosting properly in a mixed AArch32/AArch64 system.\n  \u003e\n  \u003e ARM encourages semihosting callers to implement support for trapping using `HLT`\n  \u003e on A32 and T32 as a configurable option. ARM strongly discourages semihosting\n  \u003e callers from mixing the `HLT` and `SVC` mechanisms within the same executable.\n\n  Based on the Arm's recommendation, this is implemented as an optional feature.\n\n  Note:\n  - Enabling this feature on architectures other than Arm or on Arm M-profile architecture will result in a compile error.\n\n- \u003ca name=\"optional-features-openocd-semihosting\"\u003e\u003c/a\u003e**`openocd-semihosting`**\u003cbr\u003e\n  Xtensa-specific: Use OpenOCD Semihosting.\n\n  Xtensa has two semihosting interfaces:\n\n  - Tensilica ISS SIMCALL used in Cadence tools and [QEMU](https://www.qemu.org/docs/master/about/emulation.html#supported-targets).\n  - 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).)\n\n  When this feature is enabled, this crate uses the latter interface.\n\n  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.\n\n  Note:\n  - Enabling this feature on architectures other than Xtensa will result in a compile error.\n\n- **`portable-atomic`**\u003cbr\u003e\n  Use [portable-atomic]'s atomic types.\n\n  portable-atomic provides atomic CAS on targets where the standard library does not provide atomic CAS.\n  To use the `panic-unwind` feature on such targets (e.g., RISC-V without A-extension), you need to enable this feature.\n\n  See [its documentation](https://github.com/taiki-e/portable-atomic#optional-features-critical-section) for details.\n\n- **`args`**\u003cbr\u003e\n  Enable `semihosting::experimental::env::args`.\n\n  Note:\n  - This feature is experimental (tracking issue: [#1](https://github.com/taiki-e/semihosting/issues/1))\n    and outside of the normal semver guarantees and minor or patch versions of semihosting may make\n    breaking changes to them at any time.\n\n- **`time`**\u003cbr\u003e\n  Enable `semihosting::experimental::time`.\n\n  Note:\n  - This feature is experimental (tracking issue: [#2](https://github.com/taiki-e/semihosting/issues/2))\n    and outside of the normal semver guarantees and minor or patch versions of semihosting may make\n    breaking changes to them at any time.\n\n- **`random`**\u003cbr\u003e\n  Enable `semihosting::experimental::random`.\n\n  Note:\n  - This feature is experimental (tracking issue: [#22](https://github.com/taiki-e/semihosting/issues/22))\n    and outside of the normal semver guarantees and minor or patch versions of semihosting may make\n    breaking changes to them at any time.\n  - This implicitly enables the `fs` features.\n  - 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).\n\n- **`panic-unwind`**\u003cbr\u003e\n  Provide `-C panic=unwind` support for panic handler and enable\n  `semihosting::experimental::panic::catch_unwind`.\n\n  This currently uses [unwinding] crate to support unwinding.\n  See its documentation for supported platforms and requirements.\n\n  Note:\n  - This feature is experimental (tracking issue: [#3](https://github.com/taiki-e/semihosting/issues/3))\n    and outside of the normal semver guarantees and minor or patch versions of semihosting may make\n    breaking changes to them at any time.\n  - This currently requires nightly compiler.\n  - This implicitly enables the `alloc` and `panic-handler` features.\n  - 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).\n  - When enabling this feature, you may need to rebuild the standard library with\n    `-C panic=unwind` for `catch_unwind` to work properly. The recommended way to\n    rebuild the standard library is passing `-Z build-std=\"core,alloc\"` option to cargo.\n\n- **`backtrace`**\u003cbr\u003e\n  Provide backtrace support for panic handler.\n\n  This currently uses [unwinding] crate to support backtrace.\n  See its documentation for supported platforms and requirements.\n\n  Note:\n  - This feature is experimental (tracking issue: [#3](https://github.com/taiki-e/semihosting/issues/3))\n    and outside of the normal semver guarantees and minor or patch versions of semihosting may make\n    breaking changes to them at any time.\n  - This implicitly enables the `stdio` feature.\n  - 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.)\n  - Currently, the backtrace generated is not human-readable.\n\n    ```text\n    panicked at 'a', src/main.rs:86:13\n    stack backtrace:\n      0x84dc0\n      0x8ed80\n      0x8332c\n      0x83654\n      0x80644\n      0x803cc\n      0x809dc\n      0x800bc\n    ```\n\n    You can use `addr2line` to resolve the addresses and [rustfilt] to demangle Rust symbols.\n    For example, run the following command (please replace `\u003cpath/to/binary\u003e` with your binary path), then paste the addresses:\n\n    ```sh\n    llvm-addr2line -fipe \u003cpath/to/binary\u003e | rustfilt\n    ```\n\n[portable-atomic]: https://github.com/taiki-e/portable-atomic\n[rustfilt]: https://github.com/luser/rustfilt\n[unwinding]: https://github.com/nbdd0121/unwinding\n\n\u003c!-- tidy:sync-markdown-to-rustdoc:end --\u003e\n\n## License\n\nLicensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or\n[MIT license](LICENSE-MIT) at your option.\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, as defined in the Apache-2.0 license, shall\nbe dual licensed as above, without any additional terms or conditions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaiki-e%2Fsemihosting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaiki-e%2Fsemihosting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaiki-e%2Fsemihosting/lists"}