Trait Arch

pub trait Arch {
    type Usize: Debug + FromPrimitive + PrimInt + Unsigned + BeBytes + LeBytes;
    type Registers: Registers<ProgramCounter = Self::Usize>;
    type BreakpointKind: BreakpointKind;
    type RegId: RegId;

    // Provided methods
    fn target_description_xml() -> Option<&'static str> { ... }
    fn lldb_register_info(reg_id: usize) -> Option<RegisterInfo<'static>> { ... }
}

Encodes architecture-specific information, such as pointer size, register layout, etc…

Types implementing Arch should be Zero-variant Enums, as Arch impls are only ever used at the type level, and should never be explicitly instantiated.

Required Associated Types

type Usize: Debug + FromPrimitive + PrimInt + Unsigned + BeBytes + LeBytes

The architecture’s pointer size (e.g: u32 on a 32-bit system).

type Registers: Registers<ProgramCounter = Self::Usize>

The architecture’s register file. See Registers for more details.

type BreakpointKind: BreakpointKind

The architecture’s breakpoint “kind”, used to determine the “size” of breakpoint to set. See BreakpointKind for more details.

type RegId: RegId

Register identifier enum/struct.

Used to access individual registers via Target::read/write_register.

NOTE: An arch’s RegId type is not strictly required to have a 1:1 correspondence with the Registers type, and may include register identifiers which are separate from the main Registers structure. (e.g: the RISC-V Control and Status registers)

Provided Methods

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

(optional) Return the arch’s description XML file (target.xml).

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

fn lldb_register_info(reg_id: usize) -> Option<RegisterInfo<'static>>

(optional) (LLDB extension) Return register info for the specified register.

Implementing this method enables LLDB to dynamically query the target’s register information one by one.

Some targets don’t have register context in the compiled version of the debugger. Help the debugger by dynamically supplying the register info from the target. The debugger will request the register info in a sequential manner till an error packet is received. In LLDB, the register info search has the following order:

1. Use the target definition python file if one is specified.
2. If the target definition doesn’t have any of the info from the target.xml (registers) then proceed to read the target.xml.
3. Fall back on the qRegisterInfo packets.
4. Use hardcoded defaults if available.

See the LLDB gdb-remote docs for more details on the available information that a single register can be described by and #99 for more information on LLDB compatibility.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors