有关 gdbstub 在版本 1.0.0 稳定API之前还需要实现哪些功能的更多信息，请参阅 未来计划 + 路线图。

调试功能

尽管GDB远程串行协议非常复杂，支持诸如远程文件I/O、启动新进程、"回滚"程序执行等高级功能，但幸运的是，大多数这些功能都是完全可选的。仅通过实现一些基本方法，就可以开始一个基本的调试会话。

• 基本GDB协议
  • 读取/写入内存
  • 读取/写入寄存器
  • 枚举线程

没错！这就足够了，可以让 gdb 连接上了！

当然，大多数用例还希望支持额外的调试功能。目前，gdbstub 实现了以下GDB协议扩展：

• 自动目标架构 + 功能配置
• 恢复
  • 继续
  • 单步执行
  • 范围步进
  • 反向 步进/继续
• 断点
  • 软件断点
  • 硬件断点
  • 读取/写入/访问观察点（即：值断点）
• 扩展模式
  • 启动新进程
  • 附加到现有进程
  • 终止现有进程
  • 向启动的进程传递环境变量 + 参数
  • 更改工作目录
  • 启用/禁用ASLR
• 读取内存映射（info mem）
• 读取段/段重定位偏移量
• 处理自定义 monitor 命令
  • 使用GDB的 monitor 命令扩展GDB协议以自定义调试命令！
• 主机I/O
  • 访问远程目标文件的系统以读取/写入文件
  • 可用于在附加时自动读取远程可执行文件（使用 ExecFile）
• 读取辅助向量（info auxv）
• 额外线程信息（info threads）
• 额外库信息（info sharedlibraries）

注意： GDB 功能由 gdbstub 的贡献者根据需要实现。如果您希望 gdbstub 实现缺失的 GDB 功能，请提交问题并/或打开一个 PR！

有关 GDB 远程功能的完整列表，请查看 GDB 远程配置文档，其中包含 GDB 命令及其对应的远程串行协议数据包的表格。

零开销协议扩展

通过使用称为 可内联动态扩展特性（IDETs） 的技术，gdbstub 能够利用 Rust 编译器的强大优化过程，确保在发布版本中任何未使用的功能都会被死代码消除，而无需依赖于编译时功能标志！

例如，如果您的目标没有实现自定义 GDB monitor 命令处理程序，生成的二进制文件将不包括与解析/处理底层 qRcmd 数据包相关的任何代码！

如果您对 IDETs 的工作原理感兴趣，我在文档中包含了一个简要的说明 这里。

功能标志

默认情况下，启用了 std 和 alloc 功能。

在 #![no_std] 环境中使用 gdbstub 时，请确保设置 default-features = false。

• alloc
  • 为 Box<dyn Connection> 实现 Connection。
  • 通过 log::trace! 记录外出数据包（使用堆分配的输出缓冲区）。
  • 为某些协议功能提供内置实现
    • 在 GdbStub 中使用堆分配的数据包缓冲区（如果没有通过 GdbStubBuilder::with_packet_buffer 提供）。
    • （监视命令）在 ConsoleOutput 中使用堆分配的输出缓冲区。
• std（隐含 alloc）
  • 为 TcpStream 和 UnixStream 实现 Connection。
  • 为 std::error::Error 实现 gdbstub::Error。
  • 为简化从 Target 方法中处理 std::io::Error，添加 TargetError::Io 变体。
• paranoid_unsafe
  • 有关更多详细信息，请参阅下面的 unsafe 部分。

• 虚拟机监控器 (VMMs)
  • crosvm - Chrome OS VMM
  • cloud-hypervisor - 用于现代云工作的VMM
  • uhyve - RustyHermit的轻量级虚拟机（RustyHermit）
• 操作系统内核（在 no_std 上使用 gdbstub）
  • betrusted-io/xous-core - Xous微内核操作系统
  • vmware-labs/node-replicated-kernel - x86-64（amd64）机器的一个（实验性）研究操作系统内核
• 仿真器
  • solana_rbpf - eBPF程序的虚拟机和JIT编译器
  • rustyboyadvance-ng - 任天堂Gameboy Advance仿真器和调试器（ARMv4T）
  • gamegirl - Gameboy（Color/Advance）仿真器
  • bevy-atari - Atari XL/XE仿真器（MOS 6502）
  • rmips - MIPS R3000虚拟机模拟器
  • clicky - 经典clickwheel iPod仿真器（双核ARMv4T）
  • ts7200 - TS-7200 SoC仿真器（ARMv4T）
  • vaporstation - PlayStation One仿真器（MIPS）
  • microcorruption-emu - microcorruption.com ctf的仿真器（MSP430）
• 其他
  • probe-rs - 一个现代化的嵌入式调试工具包
  • udbserver - 为Unicorn Engine提供的插件GDB调试（多架构）
  • enarx - 在可信执行环境中运行应用程序的开源框架
  • icicle-emu - 一个实验性的、多架构的模糊测试专用仿真框架

树内“玩具”示例

这些示例是作为CI的一部分构建的，并保证与gdbstub的最新版本API保持更新。

• armv4t - ./examples/armv4t/
  • 一个基于ARMv4T的简单系统仿真器，具有gdbstub支持。
  • 实现了（几乎）所有可用的target::ext功能。这使得它在首次实现新的协议扩展时成为一个极好的资源！
• armv4t_multicore - ./examples/armv4t_multicore/
  • 是armv4t示例的双核变体。
  • 实现了gdbstub多线程扩展API的核心，但除此之外没有太多。
• example_no_std - ./example_no_std
  • 这是一个极简示例，展示了如何在#![no_std]项目中使用gdbstub。
  • 与 armv4t/armv4t_multicore 示例不同，本项目不包括可工作的模拟器，仅简单地模拟所有 gdbstub 函数。
  • 充当 gdbstub 的测试平台，以跟踪其大约的二进制占用空间（通过 check_size.sh 脚本），以及验证某些死代码消除优化。

unsafe 在 gdbstub 中的使用

gdbstub 将对 unsafe 的使用限制在最低限度，所有使用 unsafe 的地方都需要有相应的 // SAFETY 注释作为理由。

对于那些对信任第三方 unsafe 代码感到担忧的人，gdbstub 提供了一个可选的 paranoid_unsafe 功能，该功能在 gdbstub crate 的整个范围内启用 #![forbid(unsafe_code)]，将所有 unsafe 代码实例替换为等效的（尽管性能较低）替代方案。

以下列表详尽地记录了 gdbstub 中所有 unsafe 的使用情况

• 使用 default 功能

  • 不发出可证明无法到达的恐慌
    • src/protocol/packet.rs：在 PacketBuf 中使用存储的子 Range<usize> 到缓冲区的索引的方法
    • src/protocol/common/hex.rs：decode_hex_buf

• 当启用 std 功能时

  • src/connection/impls/unixstream.rs：一个实现 UnixStream::peek 的方法，它使用 libc::recv。一旦 rust-lang/rust#76923 在 stdlib 中稳定了这个功能，它将被删除。

编写无恐慌代码

理想情况下，Rust 编译器应该有一些方法可以启用严格的“无恐慌”模式。不幸的是，在撰写本文时（2022/04/24），还没有这样的模式。因此，避免 Rust 编译器和 stdlib 的隐式恐慌的唯一方法是编写代码时要非常小心，并 手动检查 那些恐慌路径是否被优化掉了！

当我说“手动检查”时，我的意思是 检查生成的汇编输出。

为什么要付出这么大的努力？

• 恐慌基础设施可能非常 昂贵，当你在针对嵌入式系统优化时，panic 基础设施会将数百个额外的字节带到最终的二进制文件中。
• gdbstub 可以用于实现低级调试器，如果调试器本身出现恐慌，那么...你不太可能轻易地调试它！

因此，gdbstub 承诺在以下条件下将零额外的恐慌引入现有项目

1. 二进制文件以发布模式编译
   • *受使用的特定 rustc 版本的影响（代码生成和优化在不同版本之间有所不同）
   • *不同的硬件架构可能受到不同的编译器优化的影响
     • 例如：目前只有 x86 被积极测试以确保无panic
2. gdbstub 的 paranoid_unsafe cargo 特性已被 禁用
   • LLVM 无法在不包含一些 unsafe 代码的情况下省略某些 panic 检查
   • 有关 gdbstub 中的 unsafe 的更多信息，请参阅unsafe 部分
3. 正在使用的 Arch 实现不包括 panic 代码
   • 注意： 在 gdbstub_arch 下的架构实现并不保证一定是无panic的！
   • 如果您在 gdbstub_arch 中发现了一个 panic 架构，请考虑提交一个 PR 来修复它

如果您在无 panic 项目的环境中使用 gdbstub，并确定 gdbstub 是引入 panic 代码路径的罪魁祸首，请提交一个问题！

未来计划 + 路线图至 1.0.0

虽然 GDB 协议的绝大多数功能（例如：远程文件系统支持、tracepoint 数据包、大多数查询数据包等）不应需要破坏性 API 变更，但以下功能很可能需要至少一些破坏性 API 变更，因此应该在 1.0.0 之前实现。

请注意，这并不是一个详尽的列表，并且可能会发生变化。

• 通过 Arch 特性允许对目标特性进行细粒度控制（#12）
• 实现 GDB 的各种高级操作模式
  • 单/多线程调试
  • 多进程调试（#124）
    • 需要添加一个新的 target::ext::base::multiprocess API。
    • 注意： gdbstub 已经在“幕后”实现了多进程扩展，并硬编码了一个假的 PID，所以这主要是一个“投入工作”的问题。
  • 扩展模式（target extended-remote）
  • 非停止模式
• 有一个 gdbstub 在“裸机”环境中运行的示例（#![no_std]）