0.7.1

New Protocol Extensions

• LibrariesSvr4 - List an SVR4 (System-V/Unix) target's libraries. #142 (alexcrichton)

0.7.0

0.7 is a fairly minimal "cleanup" release, landing a collection of small breaking changes that collectively improve various ergonomic issues in gdbstub's API.

The breaking changes introduced in 0.7 are generally trivial to fix, and I wager that porting from 0.6 to 0.7 shouldn't take more than ~10 minutes, at most.

As always, check out the transition guide for a rundown of key breaking changes to watch out for.

Cheers!

---

Breaking API Changes

• stub::GdbStubError is now an opaque struct with a handful of methods to extract user-defined context (as opposed to being an enum that directly exposed all error internals to the user).
  • This change will enable future versions of gdbstub to fearlessly improve error messages and infrastructure without making semver breaking changes. See #112 for more.
• common::Signal is not longer an enum, and is instead a struct with a single pub u8 field + a collection of associated constants.
  • As a result, yet another instance of unsafe could be removed from the codebase!
• Arch API:
  • Entirely removed single_step_behavior. See #132 for details and rationale
• Target APIs:
  • SingleThreadBase/MultiThreadBase
    • read_addrs now returns a usize instead of a (), allowing implementations to report cases where only a subset of memory could be read. #115 (geigerzaehler)
  • HostIo
    • bitflags has been updated from 1.x to 2.x, affecting the type of HostIoOpenFlags and HostIoOpenMode #138 (qwandor)

Internal Improvements

• Reformatted codebase with nightly rustfmt using imports_granularity = "Item"

0.6.6

New Features

• Target::use_no_ack_mode - toggle support for for activating "no ack mode" #135 (bet4it)

0.6.5

New Protocol Extensions

• ExtendedMode > CurrentActivePid - Support reporting a non-default active PID #133
  • Required to fix vAttach behavior (see Bugfixes section below)

Bugfixes

• Fix for targets with no active threads #127 (xobs)
• Fix vAttach behavior when switching between multiple processes #129 (xobs), and #133
• Minor doc fixes

0.6.4

Bugfixes

• Avoid truncating X packets that contain : and , as part of the payload. #121 (709924470)

Internal Improvements

• Various README tweaks
• Remove some unsafe code
• CI improvements
  • Run no-panic checks on example_no_std
  • Run CI on docs

0.6.3

New Features

• SingleRegisterAccess: Support reporting unavailable regs #107 (ptosi)

---

gdbstub_arch 0.2.4 is also out:

• Add support for AArch64 #109 (ptosi)

0.6.2

0.6.2

New Protocol Extensions

• MultiThreadBase > ThreadExtraInfo - Provide extra information per-thread. #106 (thefaxman)
• LldbRegisterInfo - (LLDB specific) Report register information in the LLDB format. #103 (jawilk)
  • This information can be statically included as part of the Arch implemention, or dynamically reported via the LldbRegisterInfoOverride IDET.

Bugfixes

• Report thread ID in response to ? packet. #105 (thefaxman)

Internal Improvements

• Tweak enabled clippy lints
• Added a light dusting of #[inline] across the packet parsing code, crunching the code down even further
• Expanded on "no-panic guarantee" docs

0.6.1

• Add LLDB-specific HostIoOpenFlags #100 (mrk)

0.6.0

After over a half-year of development, gdbstub 0.6 has finally been released!

This massive release delivers a slew of new protocol extensions, internal improvements, and key API improvements. Some highlights include:

• A new non-blocking GdbStubStateMachine API, enabling gdbstub to integrate nicely with async event loops!
  • Moreover, on no_std platforms, this new API enables gdbstub to be driven directly via breakpoint/serial interrupt handlers!
  • This API is already being used in several Rust kernel projects, such as vmware-labs/node-replicated-kernel and betrusted-io/xous-core to enable bare-metal, in-kernel debugging.
• gdbstub is now entirely panic free in release builds!
  • * subject to rustc's compiler optimizations
  • This was a pretty painstaking effort, but the end result is a substantial reduction in binary size on no_std platforms.
• Tons of new and exciting protocol extensions, including but not limited to:
  • Support for remote file I/O (reading/writing files to the debug target)
  • Fetching remote memory maps
  • Catching + reporting syscall entry/exit conditions
  • ...and many more!
• A new license: gdbtsub is licensed under MIT OR Apache-2.0

See the changelog for a comprehensive rundown of all the new features.

While this release does come with quite a few breaking changes, the core IDET-based Target API has remained much the same, which should make porting code over from 0.5.x to 0.6 pretty mechanical. See the transition_guide.md for guidance on upgrading from 0.5.x to 0.6.

And as always, a huge shoutout to the folks who contributed PRs, Issues, and ideas to gdbstub - this release wouldn't have been possible without you! Special shoutouts to gz and xobs for helping me test and iterate on the new bare-metal state machine API, and bet4it for pointing out and implementing many useful API improvements and internal refactors.

Cheers!

New Features

• The new GdbStubStateMachine API gives users the power and flexibility to integrate gdbstub into their project-specific event loop infrastructure.
  • e.g: A global instance of GdbStubStateMachine can be driven directly from bare-metal interrupt handlers in no_std environments
  • e.g: A project using async/await can wrap GdbStubStateMachine in a task, yielding execution while waiting for the target to resume / new data to arrive down the Connection
• Removed all panicking code from gdbstub
  • See the commit message for more details on how this was achieved.
• Introduced strongly-typed enum for protocol defined signal numbers (instead of using bare u8s)
• Added basic feature negotiation to support clients that don't support multiprocess+ extensions.
• Relicensed gdbstub under MIT OR Apache-2.0 #68
• Added several new "guard rails" to avoid common integration footguns:
  • Target::guard_rail_implicit_sw_breakpoints - guards against the GDB client silently overriding target instructions with breakpoints if SwBreakpoints hasn't been implemented.
  • Target::guard_rail_single_step_gdb_behavior - guards against a GDB client bug where support for single step may be required / ignored on certain platforms (e.g: required on x86, ignored on MIPS)
• Added several new "toggle switches" to enable/disable parts of the protocol (all default to true)
  • Target::use_x_upcase_packet - toggle support for the more efficient X memory write packet
  • Target::use_resume_stub - toggle gdbstub's built-in "stub" resume handler that returns SIGRAP if a target doesn't implement support for resumption
  • Target::use_rle - toggle whether outgoing packets are Run Length Encoded (RLE)

New Protocol Extensions

• MemoryMap - Get memory map XML file from the target. #54 (Tiwalun)
• CatchSyscalls - Enable and disable catching syscalls from the inferior process. #57 (mchesser)
• HostIo - Perform I/O operations on host. #66 (bet4it)
  • Support for all Host I/O operations: open, close, pread, pwrite, fstat, unlink, readlink, setfs
• ExecFile - Get full absolute path of the file that was executed to create a process running on the remote system. #69 (bet4it)
• Auxv - Access the target’s auxiliary vector. #86 (bet4it)
• Implement X packet - More efficient bulk-write to memory (superceding the M packet). #82 (gz)

Breaking API Changes

• Connection API:
  • Removed the read and peek methods from Connection
    • These have been moved to the new ConnectionExt trait, which is used in the new GdbStub::run_blocking API
• Arch API:
  • Dynamic read_register + RegId support. #85 (bet4it)
• Target APIs:
  • prefix all IDET methods with support_
    • _makes it far easier to tell at-a-glance whether a method is an IDET, or an actual handler method.
  • Introduce strongly-typed enum for protocol defined signal numbers (instead of using bare u8s)
  • Base API:
    • Make single-stepping optional #92
    • Remove GdbInterrupt type (interrupt handling lifted to higher-level APIs)
    • Remove ResumeAction type (in favor of separate methods for various resume types)
  • Breakpoints API:
    • HwWatchpoint: Plumb watchpoint length parameter to public API
  • TargetXml API:
    • Support for <xi:include> in target.xml, which required including the annex parameter in the handler method.
    • annex is set to b"target.xml" on the fist call, though it may be set to other values in subsequent calls if <xi:include> is being used.
  • Pass PacketBuf-backed &mut [u8] as a response buffer to various APIs #72 (bet4it)
    • Improvement over the callback-based approach.
    • This change is possible thanks to a clause in the GDB spec that specifies that responses will never exceed the size of the PacketBuf.
    • Also see #70, which tracks some other methods that might be refactored to use this approach in the future.

Internal Improvements

• Documentation
  • Fix crates.io badges #71 (atouchet)
  • Add uhyve to real-world examples #73 (mkroening)
• Use stable clippy in CI
• Enable logging for responses with only alloc #78 (gz)
• Lots of internal refactoring and cleanup

0.5.0

0.5.0

While the overall structure of the API has remained the same, 0.5.0 does introduce a few breaking API changes that require some attention. That being said, it should not be a difficult migration, and updating to 0.5.0 from 0.4 shouldn't take more than 10 mins of refactoring.

Check out transition_guide.md for guidance on upgrading from 0.4.x to 0.5.

New Features

• Implement Run-Length-Encoding (RLE) on outgoing packets
  • This significantly cuts down on the data being transferred over the wire when reading from registers/memory
• Add target-specific kind: Arch::BreakpointKind parameters to the Breakpoint API
  • While emulated systems typically implement breakpoints by pausing execution once the PC hits a certain value, "real" systems typically need to patch the instruction stream with a breakpoint instruction. On systems with variable-sized instructions, this kind parameter specifies the size of the instruction that should be injected.
• Implement ResumeAction::{Step,Continue}WithSignal
• Added the Exited(u8), Terminated(u8), and ReplayLog("begin"|"end") stop reasons.
• Added DisconnectReason::Exited(u8) and DisconnectReason::Terminated(u8).
• Reworked the MultiThreadOps::resume API to be significantly more ergonomic and efficient
  • See the transition guide for more details.

New Protocol Extensions

• {Single,Multi}ThreadReverse{Step,Continue} - Support for reverse-step and reverse-continue. #48 (DrChat)
• {Single,Multi}ThreadRangeStepping - Optional optimized range stepping support.

Breaking Arch Changes

• gdbstub::arch has been moved into a separate gdbstub_arch crate
  • See #45 for details on why this was done.
• (x86) Break GPRs & SRs into individual fields/variants #34

Breaking API Changes

• Base Protocol Refactors
  • Reworked the MultiThreadOps::resume API
  • Added a wrapper around the raw check_gdb_interrupt callback, hiding the underlying implementation details
  • Extracted base protocol single-register access methods ({read,write}_register) into separate SingleRegisterAccess trait
    • These are optional GDB protocol methods, and as such, should be modeled as IDETs
• Protocol Extension Refactors
  • Consolidated the {Hw,Sw}Breakpoints/Watchpoints IDETs under a single Breakpoints IDET + sub-IDETs
  • Added new arch-specific kind: Arch::BreakpointKind parameter to add_{hw,sw}_breakpoint methods
  • Renamed target::ext::extended_mod::ConfigureASLR{Ops} to ConfigureAslr{Ops} (clippy::upper_case_acronyms)
• Added {Step,Continue}WithSignal variants to target::ext::base::ResumeAction
• Trait Changes
  • arch::Arch: Added type BreakpointKind. Required to support arch-specific breakpoint kinds
  • arch::Arch: (very minor) Added num_traits::FromPrimitive bound to Arch::Usize
  • arch::Registers: Added type ProgramCounter and associated fn pc(&self) -> Self::ProgramCounter method. Added preemptively in anticipation of future GDB Agent support
• Removed the Halted stop reason (more accurate to simply return {Exited|Terminated}(SIGSTOP) instead).
• Removed the Halted disconnect reason (replaced with the Exited and Terminated stop reasons instead).
• Removed the implicit ExtendedMode attached PID tracking when alloc was available. See 23b56038 rationale behind this change.

Internal Improvements

• Split monolithic GdbStubImpl implementation into separate files (by protocol extension)
• Finally rewrite + optimize GdbStubImpl::do_vcont, along with streamlining its interactions with the legacy s and c packets
• Sprinkle more IDET-based dead code elimination hints (notably wrt. stop reasons)
• Remove the default self.current_mem_tid hack, replacing it with a much more elegant solution
• Packet Parser improvements
  • Remove last remaining bit of UTF-8 related code
  • Eliminate as much panicking bounds-checking code as possible
  • support efficient parsing of packets that are parsed differently depending on active protocol extension (namely, the breakpoint packets)
  • (currently unused) Zero-cost support for parsing Z and z packets with embedded agent bytecode expressions
• Use intra-doc links whenever possible

Bugfixes

• Fix RiscvRegId for arch::riscv::Riscv64 #46 (fzyz999)