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, enablinggdbstub
to integrate nicely with async event loops!- Moreover, on
no_std
platforms, this new API enablesgdbstub
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
andbetrusted-io/xous-core
to enable bare-metal, in-kernel debugging.
- Moreover, on
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.
- * subject to
- 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 integrategdbstub
into their project-specific event loop infrastructure.- e.g: A global instance of
GdbStubStateMachine
can be driven directly from bare-metal interrupt handlers inno_std
environments - e.g: A project using
async
/await
can wrapGdbStubStateMachine
in a task, yielding execution while waiting for the target to resume / new data to arrive down theConnection
- e.g: A global instance of
- 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
u8
s) - 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 ifSwBreakpoints
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 efficientX
memory write packetTarget::use_resume_stub
- togglegdbstub
's built-in "stub" resume handler that returnsSIGRAP
if a target doesn't implement support for resumptionTarget::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
- Support for all Host I/O operations:
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 theM
packet). #82 (gz)
Breaking API Changes
Connection
API:- Removed the
read
andpeek
methods fromConnection
- These have been moved to the new
ConnectionExt
trait, which is used in the newGdbStub::run_blocking
API
- These have been moved to the new
- Removed the
Arch
API: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
u8
s) 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 watchpointlength
parameter to public API
TargetXml
API:- Support for
<xi:include>
in target.xml, which required including theannex
parameter in the handler method. annex
is set tob"target.xml"
on the fist call, though it may be set to other values in subsequent calls if<xi:include>
is being used.
- Support for
- 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.
- prefix all IDET methods with