Trait gdbstub::target::Target

source ·

pub trait Target {
    type Arch: Arch;
    type Error;

Show 20 methods    // Required method
    fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>;

    // Provided methods
    fn guard_rail_implicit_sw_breakpoints(&self) -> bool { ... }
    fn use_no_ack_mode(&self) -> bool { ... }
    fn use_x_upcase_packet(&self) -> bool { ... }
    fn use_resume_stub(&self) -> bool { ... }
    fn use_rle(&self) -> bool { ... }
    fn use_target_description_xml(&self) -> bool { ... }
    fn use_lldb_register_info(&self) -> bool { ... }
    fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>> { ... }
    fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>> { ... }
    fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>> { ... }
    fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>> { ... }
    fn support_target_description_xml_override(
        &mut self
    ) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>> { ... }
    fn support_lldb_register_info_override(
        &mut self
    ) -> Option<LldbRegisterInfoOverrideOps<'_, Self>> { ... }
    fn support_memory_map(&mut self) -> Option<MemoryMapOps<'_, Self>> { ... }
    fn support_catch_syscalls(&mut self) -> Option<CatchSyscallsOps<'_, Self>> { ... }
    fn support_host_io(&mut self) -> Option<HostIoOps<'_, Self>> { ... }
    fn support_exec_file(&mut self) -> Option<ExecFileOps<'_, Self>> { ... }
    fn support_auxv(&mut self) -> Option<AuxvOps<'_, Self>> { ... }
    fn support_libraries_svr4(&mut self) -> Option<LibrariesSvr4Ops<'_, Self>> { ... }
}

Expand description

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

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 anyone who uses the library!

Please refer to the the documentation in the target module for more information on how to implement and work with Target and its various extension traits.

Required Associated Types§

source

type Arch: Arch

The target’s architecture.

source

type Error

A target-specific fatal error.

Required Methods§

source

fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>

Base operations such as reading/writing from memory/registers, stopping/resuming the target, etc….

For example, on a single-threaded target:

use gdbstub::target::Target;
use gdbstub::target::ext::base::BaseOps;
use gdbstub::target::ext::base::singlethread::SingleThreadBase;

impl Target for MyTarget {
    // ...

    fn base_ops(&mut self) -> BaseOps<Self::Arch, Self::Error> {
        BaseOps::SingleThread(self)
    }
}

// ...and then implement the associated base IDET
impl SingleThreadBase for MyTarget {
    // ...
}

Provided Methods§

source

fn guard_rail_implicit_sw_breakpoints(&self) -> bool

If the target supports resumption, but hasn’t implemented explicit support for software breakpoints (via SwBreakpoints), notify the user that the GDB client may set “implicit” software breakpoints by rewriting the target’s instruction stream.

Targets that wish to use the GDB client’s implicit software breakpoint handler must explicitly opt-in to this somewhat surprising GDB feature by overriding this method to return true.

Context

An “implicit” software breakpoint is set by the GDB client by manually writing a software breakpoint instruction into target memory via the target’s write_addrs implementation. i.e: the GDB client will overwrite the target’s instruction stream with a software breakpoint instruction, with the expectation that the target has a implemented a breakpoint exception handler.

Implications

While this is a reasonable (and useful!) bit of behavior when targeting many classes of remote stub (e.g: bare-metal, separate process), there are many gdbstub implementations that do not implement “software breakpoints” by naively rewriting the target’s instruction stream.

e.g: a gdbstub implemented in an emulator is unlikely to implement “software breakpoints” by hooking into the emulated hardware’s breakpoint handler, and would likely implement “breakpoints” by maintaining a list of addresses to stop at as part of its core interpreter loop.
e.g: a gdbstub implemented in a hypervisor would require special coordination with the guest kernel to support software breakpoints, as there would need to be some way to distinguish between “in-guest” debugging, and “hypervisor” debugging.

As such, gdbstub includes this guard_rail_implicit_sw_breakpoints method.

As the name suggests, this method acts as a “guard rail” that warns users from accidentally opting into this “implicit” breakpoint functionality, and being exceptionally confused as to why their target is acting weird.

If gdbstub detects that the target has not implemented a software breakpoint handler, it will check if guard_rail_implicit_sw_breakpoints() has been enabled, and if it has not, it will trigger a runtime error that points the user at this very documentation.

A note on breakpoints

Aside from setting breakpoints at the explicit behest of the user (e.g: when setting breakpoints via the b command in GDB), the GDB client may also set/remove temporary breakpoints as part of other commands.

e.g: On targets without native support for hardware single-stepping, calling stepi in GDB will result in the GDB client setting a temporary breakpoint on the next instruction + resuming via continue instead.

source

fn use_no_ack_mode(&self) -> bool

Enable/disable support for activating “no ack mode”.

By default, this method returns true.

Author’s note: Unless you’re using gdbstub with a truly unreliable transport line (e.g: a noisy serial connection), it’s best to support “no ack mode”, as it can substantially improve debugging latency.

Warning: gdbstub doesn’t currently implement all necessary features for running correctly over a unreliable transport! See issue #137 for details.

What is “No Ack Mode”?

From the GDB RSP docs:

By default, when either the host or the target machine receives a packet, the first response expected is an acknowledgment: either ‘+’ (to indicate the package was received correctly) or ‘-’ (to request retransmission). This mechanism allows the GDB remote protocol to operate over unreliable transport mechanisms, such as a serial line.

In cases where the transport mechanism is itself reliable (such as a pipe or TCP connection), the ‘+’/‘-’ acknowledgments are redundant. It may be desirable to disable them in that case to reduce communication overhead, or for other reasons. This can be accomplished by means of the ‘QStartNoAckMode’ packet

source

fn use_x_upcase_packet(&self) -> bool

Enable/disable using the more efficient X packet to write to target memory (as opposed to the basic M packet).

By default, this method returns true.

Author’s note: Unless you’re really trying to squeeze gdbstub onto a particularly resource-constrained platform, you may as well leave this optimization enabled.

source

fn use_resume_stub(&self) -> bool

Whether gdbstub should provide a “stub” resume implementation on targets without support for resumption.

At the time of writing, the mainline GDB client does not gracefully handle targets that do not support support resumption, and will hang indefinitely if a user inadvertently attempts to continue or step such a target.

To make the gdbstub user experience a bit better, the library includes bit of “stub” code to gracefully handle these cases.

If a user attempts to resume a target that hasn’t implemented support for resumption, gdbstub will write a brief message back to the GDB client console, and will immediately return a “stopped with TRAP” stop reason.

This method controls whether or not this bt of behavior is enabled.

Author’s note: Unless you’re really trying to squeeze gdbstub onto a particularly resource-constrained platform, you may as well leave this enabled. The resulting stub code is entirely optimized out on targets that implement support for resumption.

source

fn use_rle(&self) -> bool

Enable/Disable the use of run-length encoding on outgoing packets.

This is enabled by default, as RLE can save substantial amounts of bandwidth down the wire.

Author’s note: There are essentially no reasons to disable RLE, unless you happen to be using a custom GDB client that doesn’t support RLE.

source

fn use_target_description_xml(&self) -> bool

Whether to send a target description XML to the client.

Setting this to false will override both Target::support_target_description_xml_override and the associated Arch::target_description_xml.

Author’s note: Having the GDB client autodetect your target’s architecture and register set is really useful, so unless you’re really trying to squeeze gdbstub onto a particularly resource-constrained platform, you may as well leave this enabled.

source

fn use_lldb_register_info(&self) -> bool

(LLDB extension) Whether to send register information to the client.

Setting this to false will override both Target::support_lldb_register_info_override and the associated Arch::lldb_register_info.

Author’s note: Having the LLDB client autodetect your target’s register set is really useful, so unless you’re really trying to squeeze gdbstub onto a particularly resource-constrained platform, you may as well leave this enabled.

source