Trait gdbstub::target::Target

source · [−]
pub trait Target {
    type Arch: Arch;
    type Error;

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

    fn guard_rail_implicit_sw_breakpoints(&self) -> bool { ... }

    fn guard_rail_single_step_gdb_behavior(&self) -> SingleStepGdbBehavior { ... }

    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 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_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>> { ... }

}
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.

Associated Types

The target’s architecture.

A target-specific fatal error.

Required methods

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

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.

If you are reading these docs after having encountered a GdbStubError::ImplicitSwBreakpoints error, it’s quite likely that you’ll want to implement explicit support for software breakpoints.

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.

Override the arch-level value for Arch::single_step_gdb_behavior.

If you are reading these docs after having encountered a GdbStubError::SingleStepGdbBehavior error, you may need to either:

  • implement support for single-step
  • disable existing support for single step
  • be a Good Citizen and perform a quick test to see what kind of behavior your Arch exhibits.
WARNING

Unless you really know what you’re doing (e.g: working on a dynamic target implementation, attempting to fix the underlying bug, etc…), you should not override this method, and instead follow the advice the error gives you.

Incorrectly setting this method may lead to “unexpected packet” runtime errors!

Details

This method provides an “escape hatch” for disabling a workaround for a bug in the mainline GDB client implementation.

To squelch all errors, this method can be set to return SingleStepGdbBehavior::Optional (though as mentioned above - you should only do so if you’re sure that’s the right behavior).

For more information, see the documentation for Arch::single_step_gdb_behavior.

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.

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.

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.

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.

Support for setting / removing breakpoints.

Support for handling custom GDB monitor commands.

Support for Extended Mode operations.

Support for handling requests to get the target’s current section (or segment) offsets.

Support for overriding the target description XML specified by Target::Arch.

Support for reading the target’s memory map.

Support for setting / removing syscall catchpoints.

Support for Host I/O operations.

Support for reading the current exec-file.

Support for reading the target’s Auxillary Vector.

Trait Implementations

The target’s architecture.

A target-specific fatal error.

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

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. Read more

Override the arch-level value for Arch::single_step_gdb_behavior. Read more

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

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

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

Whether to send a target description XML to the client. Read more

Support for setting / removing breakpoints.

Support for handling custom GDB monitor commands.

Support for Extended Mode operations.

Support for handling requests to get the target’s current section (or segment) offsets. Read more

Support for overriding the target description XML specified by Target::Arch. Read more

Support for reading the target’s memory map.

Support for setting / removing syscall catchpoints.

Support for Host I/O operations.

Support for reading the current exec-file.

Support for reading the target’s Auxillary Vector.

Implementations on Foreign Types

Implementors