[−][src]Trait gdbstub::Target

pub trait Target {
    type Usize: PrimInt + Unsigned + Debug;
    type Error;
    fn step(
        &mut self, 
        log_mem_access: impl FnMut(Access<Self::Usize>)
    ) -> Result<TargetState, Self::Error>;

    fn read_registers(&mut self, push_reg: impl FnMut(&[u8]));

    fn write_registers(&mut self, regs: &[u8]);

    fn read_pc(&mut self) -> Self::Usize;

    fn read_addrs(&mut self, addr: Range<Self::Usize>, val: impl FnMut(u8));

    fn write_addrs(
        &mut self, 
        get_addr_val: impl FnMut() -> Option<(Self::Usize, u8)>
    );

    fn target_description_xml() -> Option<&'static str> { ... }
}

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.

Loading content...

Required methods

fn step(
    &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)>
)

Write bytes to the specified address range.

Loading content...

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.

Loading content...

Implementors

Loading content...