All notable changes to this project will be documented in this file.
This project adheres to Semantic Versioning.
core_error feature, to have GdbStubError impl core::error::Error. #154 (ultimaweapon)gdbstub doesn't claim a strict MSRV at this time, it seemed unwise to have a PATCH release break folks stuck on a pre-1.81 Rust toolchain.e9a5296cLibrariesSvr4 - List an SVR4 (System-V/Unix) target's libraries. #142 (alexcrichton)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/MultiThreadBaseread_addrs now returns a usize instead of a (), allowing implementations to report cases where only a subset of memory could be read. #115 (geigerzaehler)HostIoimports_granularity = "Item"ExtendedMode > CurrentActivePid - Support reporting a non-default active PID #133vAttach behavior (see Bugfixes section below)vAttach behavior when switching between multiple processes #129 (xobs), and #133unsafe codeexample_no_stdMultiThreadBase > 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.gdbstub 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 Connectiongdbstubu8s)multiprocess+ extensions.gdbstub under MIT OR Apache-2.0 #68Target::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, setfsExecFile - 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 ConnectionConnectionExt trait, which is used in the new GdbStub::run_blocking APIArch API:Target APIs:support_u8s)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.clippy in CIWhile 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 APIkind parameter specifies the size of the instruction that should be injected.ResumeAction::{Step,Continue}WithSignalExited(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 crateMultiThreadOps::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::ResumeActionarch::Arch: Added type BreakpointKind. Required to support arch-specific breakpoint kindsarch::Arch: (very minor) Added num_traits::FromPrimitive bound to Arch::Usizearch::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 expressionsTargetDescriptionXmlOverride - Allow targets to override the target description XML file (target.xml) specified by Target::Arch::target_description_xml. This is useful in cases where a Target is expected to be generic over multiple architectures. #43 (with help from DrChat)write! instead of writeln! in output! macro #41RegId for Mips/Mips64 #38 (starfleetcadet75)RegId for MSP430 #38 (starfleetcadet75)T06 to S05,cargo build fails if cfg-if is 0.1.9 or olderTarget::Arch::Usize).This version includes a major API overhaul, alongside a slew of new features and general improvements. While updating to 0.4.0 will require some substantial code modifications, it's well worth the effort, as 0.4.0 is the safest, leanest, and most featureful release of gdbstub yet!
Fun fact: Even after adding a bunch of new features and bug-fixes, the in-tree example_no_std has remained just as small! The example on the semver-fix-0.2.2 branch is 20251 bytes, while the example on 0.4.0 is 20246 bytes.
Target API in terms of “Inlineable Dyn Extension Traits” (IDETs)Target into smaller pieces which can be mixed-and-matched, it not only makes it easier to get up-and-running with gdbstub, but it also unlocks a lot of awesome internal optimizations:add_sw_breakpoint and remove_sw_breakpoint).Target API with support for non-fatal error handling.std::io::Error that occur as a result of ExtendedMode operations. The new TargetResult/TargetError result is much more robust, and opens to door to supporting additional error handling extensions (such as LLDB's ASCII Errors).Connection trait with new methods (flush - required, write_all, on_session_start)Registers::RegId to Arch::RegId, and introduce new temporary RegIdImpl solution for avoiding breaking API changes due to new RegId implementations (see #29)RegId enums as #[non_exhaustive], allowing more registers to be added if need be.#[non_exhaustive].ExtendedMode - Allow targets to run new processes / attach to existing processes / restart execution.set disable-randomization, set environment, set startup-with-shell, and set cwd and cd.SectionOffsets - Get section/segment relocation offsets from the target. #30 (mchesser)qOffsets packet under-the-hood.set_nodelay is set when using a TcpStream as a Connection (via the new Connection::on_session_start API)btou dependency.UTF-8 aware str handling code.This version contains a few minor breaking changes from 0.2.1. These are only surface-level changes, and can be fixed with minimal effort.
Version 0.3.0 is identical to the yanked version 0.2.2, except that it adheres to cargo's modified SemVer rule which states that the pre-0.x.y breaking changes should still bump the minor version.
Thanks to h33p for reporting this issue (#27)
Target::resume API to replace raw &mut dyn Iterator with a functionally identical concrete Actions iterator.StopReason enum as #[non_exhaustive], allowing further types to be added without being considered as an API breaking change.Target::read/write_register support (to support single register accesses) #22 (thomashk0)StopReason::Signal(u8) variant, to send arbitrary signal codes #19 (mchesser)Target::resumeTarget::read/write_addrs.start of changelog