Module gdbstub::target

Everything related to the Target trait + associated extension traits.

The Target trait describes how to control and modify a system's execution state during a GDB debugging session, and serves as the primary bridge between gdbstub's generic protocol implementation and a target's project/platform-specific code.

Target is the most important trait in gdbstub, and must be implemented by all consumers of the library!

Implementing Target

gdbstub uses a technique called "Inlineable Dyn Extension Traits" (IDETs) to expose an ergonomic and extensible interface to the GDB protocol. It's not a very common pattern, and can seem a little "weird" at first glance, but it's actually very straightforward to use!

Please refer to the documentation in the ext module for more information on IDETs, and how they're used to implement Target and it's various extension traits.

TL;DR: Whenever you see a method that has Option<FooOps> in the return type, that method should return Some(self) if the extension is implemented, or None if it's unimplemented / disabled.

Associated Types

• The Target::Arch associated type encodes information about the target's architecture, such as it's pointer size, register layout, etc... gdbstub comes with several built-in architecture definitions, which can be found under the arch module.

• The Target::Error associated type allows implementors to plumb-through their own project-specific fatal error type into the Target trait. This is a big-boost to library ergonomics, as it enables consumers of gdbstub to preserve target-specific context while using gdbstub, without having to do any "error-stashing".

For example: consider an emulated target where certain devices might return a MyEmuError::ContractViolation error whenever they're accessed "improperly" (e.g: setting registers in the wrong order). By setting type Error = MyEmuError, the method signature of the Target's resume method becomes fn resume(&mut self, ...) -> Result<_, MyEmuError>, which makes it possible to preserve the target-specific error while using gdbstub!

Required Methods

The Target::base_ops method describes the base debugging operations that must be implemented by any target. These are things such as starting/stopping execution, reading/writing memory, etc..

All other methods are entirely optional! Check out the target_ext module for a full list of currently supported protocol extensions.

Example: A Bare-Minimum Single Threaded Target

use gdbstub::target::Target;
use gdbstub::target::ext::base::singlethread::SingleThreadOps;

impl SingleThreadOps for MyTarget {
    // ... omitted for brevity
}

impl Target for MyTarget {
    fn base_ops(&mut self) -> base::BaseOps<Self::Arch, Self::Error> {
        base::BaseOps::SingleThread(self)
    }
}

Modules

ext	Extensions to Target which add support for various subsets of the GDB Remote Serial Protocol.

Enums

TargetError

The error type for various methods on Target and it's assorted associated extension traits.

Traits

Target

Describes the architecture and capabilities of a target which can be debugged by GdbStub.

Type Definitions

TargetResult

A specialized Result type for Target operations.