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§
Required Methods§
sourcefn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>
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§
sourcefn guard_rail_implicit_sw_breakpoints(&self) -> bool
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.
sourcefn use_no_ack_mode(&self) -> bool
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
sourcefn use_x_upcase_packet(&self) -> bool
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.
sourcefn use_resume_stub(&self) -> bool
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.
sourcefn use_rle(&self) -> bool
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.
sourcefn use_target_description_xml(&self) -> bool
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.
sourcefn use_lldb_register_info(&self) -> bool
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.
sourcefn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
Support for setting / removing breakpoints.
sourcefn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
Support for handling custom GDB monitor
commands.
sourcefn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
Support for Extended Mode operations.
sourcefn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
Support for handling requests to get the target’s current section (or segment) offsets.
sourcefn support_target_description_xml_override(
&mut self
) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
fn support_target_description_xml_override( &mut self ) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
Support for overriding the target description XML specified by
Target::Arch
.
sourcefn support_lldb_register_info_override(
&mut self
) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
fn support_lldb_register_info_override( &mut self ) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
(LLDB extension) Support for overriding the register info specified by
Target::Arch
.
sourcefn support_memory_map(&mut self) -> Option<MemoryMapOps<'_, Self>>
fn support_memory_map(&mut self) -> Option<MemoryMapOps<'_, Self>>
Support for reading the target’s memory map.
sourcefn support_catch_syscalls(&mut self) -> Option<CatchSyscallsOps<'_, Self>>
fn support_catch_syscalls(&mut self) -> Option<CatchSyscallsOps<'_, Self>>
Support for setting / removing syscall catchpoints.
sourcefn support_host_io(&mut self) -> Option<HostIoOps<'_, Self>>
fn support_host_io(&mut self) -> Option<HostIoOps<'_, Self>>
Support for Host I/O operations.
sourcefn support_exec_file(&mut self) -> Option<ExecFileOps<'_, Self>>
fn support_exec_file(&mut self) -> Option<ExecFileOps<'_, Self>>
Support for reading the current exec-file.
sourcefn support_auxv(&mut self) -> Option<AuxvOps<'_, Self>>
fn support_auxv(&mut self) -> Option<AuxvOps<'_, Self>>
Support for reading the target’s Auxillary Vector.
sourcefn support_libraries_svr4(&mut self) -> Option<LibrariesSvr4Ops<'_, Self>>
fn support_libraries_svr4(&mut self) -> Option<LibrariesSvr4Ops<'_, Self>>
Support for reading a list of libraries for SVR4 (System-V/Unix) platforms.
Trait Implementations§
source§impl<A, E> Target for &mut dyn Target<Arch = A, Error = E>where
A: Arch,
impl<A, E> Target for &mut dyn Target<Arch = A, Error = E>where
A: Arch,
source§fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>
fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>
source§fn guard_rail_implicit_sw_breakpoints(&self) -> bool
fn guard_rail_implicit_sw_breakpoints(&self) -> bool
SwBreakpoints
), notify the user
that the GDB client may set “implicit” software breakpoints by
rewriting the target’s instruction stream. Read moresource§fn use_no_ack_mode(&self) -> bool
fn use_no_ack_mode(&self) -> bool
source§fn use_x_upcase_packet(&self) -> bool
fn use_x_upcase_packet(&self) -> bool
X
packet to write to target
memory (as opposed to the basic M
packet). Read moresource§fn use_resume_stub(&self) -> bool
fn use_resume_stub(&self) -> bool
gdbstub
should provide a “stub” resume
implementation on
targets without support for resumption. Read moresource§fn use_rle(&self) -> bool
fn use_rle(&self) -> bool
source§fn use_target_description_xml(&self) -> bool
fn use_target_description_xml(&self) -> bool
source§fn use_lldb_register_info(&self) -> bool
fn use_lldb_register_info(&self) -> bool
source§fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
source§fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
monitor
commands.source§fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
source§fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
source§fn support_target_description_xml_override(
&mut self
) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
fn support_target_description_xml_override( &mut self ) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
Target::Arch
.source§fn support_lldb_register_info_override(
&mut self
) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
fn support_lldb_register_info_override( &mut self ) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
Target::Arch
.source§fn support_memory_map(&mut self) -> Option<MemoryMapOps<'_, Self>>
fn support_memory_map(&mut self) -> Option<MemoryMapOps<'_, Self>>
source§fn support_catch_syscalls(&mut self) -> Option<CatchSyscallsOps<'_, Self>>
fn support_catch_syscalls(&mut self) -> Option<CatchSyscallsOps<'_, Self>>
source§fn support_host_io(&mut self) -> Option<HostIoOps<'_, Self>>
fn support_host_io(&mut self) -> Option<HostIoOps<'_, Self>>
source§fn support_exec_file(&mut self) -> Option<ExecFileOps<'_, Self>>
fn support_exec_file(&mut self) -> Option<ExecFileOps<'_, Self>>
source§fn support_auxv(&mut self) -> Option<AuxvOps<'_, Self>>
fn support_auxv(&mut self) -> Option<AuxvOps<'_, Self>>
source§fn support_libraries_svr4(&mut self) -> Option<LibrariesSvr4Ops<'_, Self>>
fn support_libraries_svr4(&mut self) -> Option<LibrariesSvr4Ops<'_, Self>>
source§impl<A, E> Target for Box<dyn Target<Arch = A, Error = E>>where
A: Arch,
impl<A, E> Target for Box<dyn Target<Arch = A, Error = E>>where
A: Arch,
source§fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>
fn base_ops(&mut self) -> BaseOps<'_, Self::Arch, Self::Error>
source§fn guard_rail_implicit_sw_breakpoints(&self) -> bool
fn guard_rail_implicit_sw_breakpoints(&self) -> bool
SwBreakpoints
), notify the user
that the GDB client may set “implicit” software breakpoints by
rewriting the target’s instruction stream. Read moresource§fn use_no_ack_mode(&self) -> bool
fn use_no_ack_mode(&self) -> bool
source§fn use_x_upcase_packet(&self) -> bool
fn use_x_upcase_packet(&self) -> bool
X
packet to write to target
memory (as opposed to the basic M
packet). Read moresource§fn use_resume_stub(&self) -> bool
fn use_resume_stub(&self) -> bool
gdbstub
should provide a “stub” resume
implementation on
targets without support for resumption. Read moresource§fn use_rle(&self) -> bool
fn use_rle(&self) -> bool
source§fn use_target_description_xml(&self) -> bool
fn use_target_description_xml(&self) -> bool
source§fn use_lldb_register_info(&self) -> bool
fn use_lldb_register_info(&self) -> bool
source§fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
fn support_breakpoints(&mut self) -> Option<BreakpointsOps<'_, Self>>
source§fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
fn support_monitor_cmd(&mut self) -> Option<MonitorCmdOps<'_, Self>>
monitor
commands.source§fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
fn support_extended_mode(&mut self) -> Option<ExtendedModeOps<'_, Self>>
source§fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
fn support_section_offsets(&mut self) -> Option<SectionOffsetsOps<'_, Self>>
source§fn support_target_description_xml_override(
&mut self
) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
fn support_target_description_xml_override( &mut self ) -> Option<TargetDescriptionXmlOverrideOps<'_, Self>>
Target::Arch
.source§fn support_lldb_register_info_override(
&mut self
) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
fn support_lldb_register_info_override( &mut self ) -> Option<LldbRegisterInfoOverrideOps<'_, Self>>
Target::Arch
.