此外，此库还提供半主机恐慌处理程序，支持 -C panic=unwind，通过 trap-hlt 功能 支持回溯，通过 可选功能。

平台支持

以下目标架构受到支持

主机必须运行仿真器或连接到目标的调试器。

以下目标已在 CI 上进行了测试。（qemu-system 已在 Linux、macOS 和 Windows 主机上进行了测试，qemu-user 在 Linux 主机上进行了测试。）

[1] stdio、fs、time 和 args。
[2] 我不确定如何在 qemu-user 上测试 panic-unwind。
[3] 由于 #![feature(asm_experimental_arch)]，需要使用夜间版本。
[4] 它似乎不支持 QEMU 8.0+。

可选功能

默认情况下禁用所有功能。

在一般的使用场景中，你可能只需要 stdio 功能，它启用了与打印相关的宏，以及/或 panic-handler 功能，在 panic 时会以非零错误码退出。

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

• alloc
  使用 alloc。

• stdio
  启用 semihosting::io::{stdin,stdout,stderr} 和 semihosting::{print*,eprint*,dbg}。

• fs
  启用 semihosting::fs。

• panic-handler
  基于 semihosting::process::exit 提供panic处理程序。

  如果同时启用了 stdio 功能，则会尝试将panic消息和位置输出到stderr。

• trap-hlt
  ARM专用：在A+R配置文件中使用HLT指令。

  ARM文档说明

  HLT 编码是新版本2.0的半主机接口规范中的内容。尽可能让半主机调用者继续使用先前存在的陷阱指令以确保与旧版半主机实现兼容。这些陷阱指令是 A64 的 HLT，A+R 配置文件 A32 或 T32 的 SVC，以及 M 配置文件的 BKPT。但是，为了正确支持混合 AArch32/AArch64 系统，有必要将 SVC 指令更改为 HLT 指令。

  ARM鼓励半主机调用者实现支持 A32 和 T32 的 HLT 陷阱，作为一个可配置选项。ARM强烈反对半主机调用者在同一可执行文件中混合 HLT 和 SVC 机制。

  根据ARM的建议，这被实现为一个可选功能。

  在ARM A+R配置文件以外的架构上启用此功能会导致编译错误。

• openocd-semihosting
  Xtensa专用：使用OpenOCD半主机。

  Xtensa有两个半主机接口

  • Cadence工具和 QEMU 中使用的Tensilica ISS SIMCALL。
  • 在 OpenOCD 和 probe-rs 中使用的与ARM半主机兼容的半主机接口。 (这个包称其为 "OpenOCD半主机"，与 newlib 中的选项名相同。)

  这个包目前不支持基于SIMCALL的半主机，但用户需要明确启用此功能，以避免意外选择其他不是真正想使用的选项。

  在Xtensa以外的架构上启用此功能会导致编译错误。

• portable-atomic
  使用 portable-atomic 的原子类型。

  portable-atomic 在标准库不提供原子 CAS 的目标上提供原子 CAS。要在这样的目标上使用 panic-unwind 功能（例如，没有A扩展的RISC-V），你需要启用此功能。

  有关详细信息，请参阅其文档。

• args
  启用 semihosting::experimental::env::args。

  注意

  • 此功能为实验性（跟踪问题：#1）且不在常规的semver保证范围内，semihosting的次要或补丁版本可能随时对其进行破坏性更改。

• 时间
  启用 semihosting::experimental::time。

  注意

  • 此功能为实验性（跟踪问题：#2）且不在常规的semver保证范围内，semihosting的次要或补丁版本可能随时对其进行破坏性更改。

• panic-unwind
  为panic处理器提供 -C panic=unwind 支持，并启用 semihosting::experimental::panic::catch_unwind。

  目前使用 unwinding crate 来支持unwinding。请参阅其文档以了解支持的平台和要求。

  注意

  • 此功能为实验性（跟踪问题：#3）且不在常规的semver保证范围内，semihosting的次要或补丁版本可能随时对其进行破坏性更改。
  • 需要使用nightly编译器。
  • 此功能隐式启用了 alloc 和 panic-handler 功能。
  • 此功能使用原子CAS。如果您的目标不支持原子CAS（例如，没有A扩展的RISC-V），则需要与 portable-atomic 功能一起使用。
  • 启用此功能时，您可能需要使用 -C panic=unwind 选项重新构建标准库，以便 catch_unwind 能够正常工作。重新构建标准库的推荐方法是向cargo传递 -Z build-std="core,alloc" 选项。

• backtrace
  为panic处理器提供回溯支持。

  目前使用 unwinding crate 来支持回溯。请参阅其文档以了解支持的平台和要求。

  注意

  • 此功能为实验性（跟踪问题：#3）且不在常规的semver保证范围内，semihosting的次要或补丁版本可能随时对其进行破坏性更改。

  • 需要使用nightly编译器。

  • 此功能隐式启用了 stdio 功能。

  • 启用此功能时，建议同时启用 panic-unwind 功能。否则，此时将不会显示合理的回溯。使用 -C force-unwind-tables 可能有效，但尚未进行测试。

  • 目前生成的回溯不可读。

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

    您可以使用 addr2line 解析地址，并使用 rustfilt 解除Rust符号的混淆。例如，运行以下命令（请将 <path/to/binary> 替换为您的二进制路径），然后粘贴地址

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

许可

根据您的选择，受Apache License, Version 2.0 或 MIT license 许可。

除非您明确表示，否则根据Apache-2.0许可证定义的，您有意提交的任何贡献，都应按照上述方式双重许可，不附加任何额外条款或条件。