An ergonomic, featureful, and easy-to-integrate implementation of the GDB Remote Serial Protocol in Rust (with no-compromises #![no_std] support)
LibrariesSvr4
- List an SVR4 (System-V/Unix) target's libraries. #142 (alexcrichton)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!
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).
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.
unsafe
could be removed from the codebase!
Arch
API:
single_step_behavior
. See #132 for details and rationaleTarget
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
imports_granularity = "Item"
ExtendedMode > CurrentActivePid
- Support reporting a non-default active PID #133
vAttach
behavior (see Bugfixes section below)MultiThreadBase > ThreadExtraInfo
- Provide extra information per-thread. #106 (thefaxman)LldbRegisterInfo
- (LLDB specific) Report register information in the LLDB format. #103 (jawilk)
Arch
implemention, or dynamically reported via the LldbRegisterInfoOverride
IDET.#[inline]
across the packet parsing code, crunching the code down even furtherAfter 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:
GdbStubStateMachine
API, enabling gdbstub
to integrate nicely with async event loops!
no_std
platforms, this new API enables gdbstub
to be driven directly via breakpoint/serial interrupt handlers!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!
rustc
's compiler optimizationsno_std
platforms.gdbtsub
is licensed under MIT OR Apache-2.0See 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!
GdbStubStateMachine
API gives users the power and flexibility to integrate gdbstub
into their project-specific event loop infrastructure.
GdbStubStateMachine
can be driven directly from bare-metal interrupt handlers in no_std
environmentsasync
/await
can wrap GdbStubStateMachine
in a task, yielding execution while waiting for the target to resume / new data to arrive down the Connection
gdbstub
u8
s)multiprocess+
extensions.gdbstub
under MIT OR Apache-2.0 #68
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)true
)
Target::use_x_upcase_packet
- toggle support for the more efficient X
memory write packetTarget::use_resume_stub
- toggle gdbstub
's built-in "stub" resume handler that returns SIGRAP
if a target doesn't implement support for resumptionTarget::use_rle
- toggle whether outgoing packets are Run Length Encoded (RLE)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)
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)X
packet - More efficient bulk-write to memory (superceding the M
packet). #82 (gz)Connection
API:
read
and peek
methods from Connection
ConnectionExt
trait, which is used in the new GdbStub::run_blocking
APIArch
API:
Target
APIs:
support_
u8
s)Base
API:
GdbInterrupt
type (interrupt handling lifted to higher-level APIs)ResumeAction
type (in favor of separate methods for various resume types)Breakpoints
API:
HwWatchpoint
: Plumb watchpoint length
parameter to public APITargetXml
API:
<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.PacketBuf
-backed &mut [u8]
as a response buffer to various APIs #72 (bet4it)
PacketBuf
.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
.
kind: Arch::BreakpointKind
parameters to the Breakpoint API
kind
parameter specifies the size of the instruction that should be injected.
ResumeAction::{Step,Continue}WithSignal
Exited(u8)
, Terminated(u8)
, and ReplayLog("begin"|"end")
stop reasons.DisconnectReason::Exited(u8)
and DisconnectReason::Terminated(u8)
.MultiThreadOps::resume
API to be significantly more ergonomic and efficient
{Single,Multi}ThreadReverse{Step,Continue}
- Support for reverse-step and reverse-continue. #48 (DrChat){Single,Multi}ThreadRangeStepping
- Optional optimized range stepping support.gdbstub::arch
has been moved into a separate gdbstub_arch
crate
MultiThreadOps::resume
APIcheck_gdb_interrupt
callback, hiding the underlying implementation details{read,write}_register
) into separate SingleRegisterAccess
trait
{Hw,Sw}Breakpoints/Watchpoints
IDETs under a single Breakpoints
IDET + sub-IDETskind: Arch::BreakpointKind
parameter to add_{hw,sw}_breakpoint
methodstarget::ext::extended_mod::ConfigureASLR{Ops}
to ConfigureAslr{Ops}
(clippy::upper_case_acronyms){Step,Continue}WithSignal
variants to target::ext::base::ResumeAction
arch::Arch
: Added type BreakpointKind
. Required to support arch-specific breakpoint kindsarch::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 supportHalted
stop reason (more accurate to simply return {Exited|Terminated}(SIGSTOP)
instead).Halted
disconnect reason (replaced with the Exited
and Terminated
stop reasons instead).ExtendedMode
attached PID tracking when alloc
was available. See 23b56038
rationale behind this change.GdbStubImpl
implementation into separate files (by protocol extension)GdbStubImpl::do_vcont
, along with streamlining its interactions with the legacy s
and c
packetsself.current_mem_tid
hack, replacing it with a much more elegant solutionZ
and z
packets with embedded agent bytecode expressions