Skip to content

0.6.0
Compare
Choose a tag to compare
@daniel5151 daniel5151 released this 20 Jan 17:18
· 65 commits to master since this release
0.6.0
d22eea8

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
  • 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
  • Use stable clippy in CI
  • Enable logging for responses with only alloc #78 (gz)
  • Lots of internal refactoring and cleanup
Assets 2