[−][src]Trait gdbstub::Target
Describes a target system which can be debugged using
GdbStub
.
This trait describes the architecture and capabilities of a target system,
and provides an interface for GdbStub
to modify and control the system's
state.
Several of the trait's "Provided methods" can be overwritten to enable
certain advanced GDB debugging features. For example, the
target_description_xml
method can be
overwritten to enable automatic architecture detection.
What's <target>.xml
?
Some required methods rely on target-specific information which can only be
found in GDB's internal <target>.xml
files. For example, a basic 32-bit
ARM target uses the register layout described in the
arm-core.xml
file.
Associated Types
type Usize: PrimInt + Unsigned + Debug
The target architecture's pointer size (e.g: u32
on a 32-bit system).
type Error
A target-specific fatal error.
Required methods
fn step(
&mut self,
log_mem_access: impl FnMut(Access<Self::Usize>)
) -> Result<TargetState, Self::Error>
&mut self,
log_mem_access: impl FnMut(Access<Self::Usize>)
) -> Result<TargetState, Self::Error>
Perform a single "step" of the emulated system. A step should be a single CPU instruction or less.
The provided log_mem_access
function should be called each time a
memory location is accessed.
fn read_registers(&mut self, push_reg: impl FnMut(&[u8]))
Read the target's registers.
The registers should be read in the order specified in the
<target>.xml
. The provided push_reg
function
should be called with the register's value.
fn write_registers(&mut self, regs: &[u8])
Write the target's registers.
The bytes are provided in the order specified in the target's registers
are provided in the order specified in the
<target>.xml
.
e.g: for ARM: binutils-gdb/blob/master/gdb/features/arm/arm-core.xml
fn read_pc(&mut self) -> Self::Usize
Read the target's current PC.
fn read_addrs(&mut self, addr: Range<Self::Usize>, val: impl FnMut(u8))
Read bytes from the specified address range.
fn write_addrs(
&mut self,
get_addr_val: impl FnMut() -> Option<(Self::Usize, u8)>
)
&mut self,
get_addr_val: impl FnMut() -> Option<(Self::Usize, u8)>
)
Write bytes to the specified address range.
Provided methods
fn target_description_xml() -> Option<&'static str>
Return the platform's features.xml
file.
Implementing this method enables gdb
to automatically detect the
target's architecture, saving the hassle of having to run set architecture <arch>
when starting a debugging session.
These descriptions can be quite succinct. For example, the target
description for an armv4t
platform can be as simple as:
r#"<target version="1.0"><architecture>armv4t</architecture></target>"#
See the GDB docs for details on the target description XML format.