Trait Handler

pub trait Handler {
    // Required methods
    fn attached(&self, _pid: Option<u64>) -> Result<ProcessType, Error>;
    fn halt_reason(&self) -> Result<StopReason, Error>;

    // Provided methods
    fn query_supported_features(&self) -> Vec<String> { ... }
    fn detach(&self, _pid: Option<u64>) -> Result<(), Error> { ... }
    fn kill(&self, _pid: Option<u64>) -> Result<(), Error> { ... }
    fn ping_thread(&self, _id: ThreadId) -> Result<(), Error> { ... }
    fn read_memory(&self, _region: MemoryRegion) -> Result<Vec<u8>, Error> { ... }
    fn write_memory(&self, _address: u64, _bytes: &[u8]) -> Result<(), Error> { ... }
    fn read_register(&self, _register: u64) -> Result<Vec<u8>, Error> { ... }
    fn write_register(
        &self,
        _register: u64,
        _contents: &[u8],
    ) -> Result<(), Error> { ... }
    fn read_general_registers(&self) -> Result<Vec<u8>, Error> { ... }
    fn write_general_registers(&self, _contents: &[u8]) -> Result<(), Error> { ... }
    fn read_bytes(
        &self,
        _object: String,
        _annex: String,
        _offset: u64,
        _length: u64,
    ) -> Result<(Vec<u8>, bool), Error> { ... }
    fn current_thread(&self) -> Result<Option<ThreadId>, Error> { ... }
    fn set_current_thread(
        &self,
        _for: SetThreadFor,
        _id: ThreadId,
    ) -> Result<(), Error> { ... }
    fn search_memory(
        &self,
        _address: u64,
        _length: u64,
        _bytes: &[u8],
    ) -> Result<Option<u64>, Error> { ... }
    fn invoke(&self, _: &[u8]) -> Result<String, Error> { ... }
    fn set_address_randomization(&self, _enable: bool) -> Result<(), Error> { ... }
    fn catch_syscalls(&self, _syscalls: Option<Vec<u64>>) -> Result<(), Error> { ... }
    fn set_pass_signals(&self, _signals: Vec<u64>) -> Result<(), Error> { ... }
    fn set_program_signals(&self, _signals: Vec<u64>) -> Result<(), Error> { ... }
    fn thread_info(&self, _thread: ThreadId) -> Result<String, Error> { ... }
    fn thread_list(&self, _reset: bool) -> Result<Vec<ThreadId>, Error> { ... }
    fn insert_software_breakpoint(
        &self,
        _breakpoint: Breakpoint,
    ) -> Result<(), Error> { ... }
    fn insert_hardware_breakpoint(
        &self,
        _breakpoint: Breakpoint,
    ) -> Result<(), Error> { ... }
    fn insert_write_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn insert_read_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn insert_access_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn remove_software_breakpoint(
        &self,
        _breakpoint: Breakpoint,
    ) -> Result<(), Error> { ... }
    fn remove_hardware_breakpoint(
        &self,
        _breakpoint: Breakpoint,
    ) -> Result<(), Error> { ... }
    fn remove_write_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn remove_read_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn remove_access_watchpoint(
        &self,
        _watchpoint: Watchpoint,
    ) -> Result<(), Error> { ... }
    fn query_supported_vcont(
        &self,
    ) -> Result<Cow<'static, [VContFeature]>, Error> { ... }
    fn vcont(
        &self,
        _request: Vec<(VCont, Option<ThreadId>)>,
    ) -> Result<StopReason, Error> { ... }
    fn fs(&self) -> Result<&dyn FileSystem, ()> { ... }
    fn process_symbol(
        &self,
        _sym_value: &str,
        _sym_name: &str,
    ) -> Result<SymbolLookupResponse, Error> { ... }
}

This trait should be implemented by servers. Methods in the trait generally default to returning Error::Unimplemented; but some exceptions are noted below. Methods that must be implemented in order for the server to work at all do not have a default implementation.

Required Methods

fn attached(&self, _pid: Option<u64>) -> Result<ProcessType, Error>

Indicate whether the process in question already existed, and was attached to; or whether it was created by this server.

fn halt_reason(&self) -> Result<StopReason, Error>

Return the reason that the inferior has halted.

Provided Methods

fn query_supported_features(&self) -> Vec<String>

Return a vector of additional features supported by this handler. Note that there currently is no way to override the built-in features that are always handled by the protocol implementation.

fn detach(&self, _pid: Option<u64>) -> Result<(), Error>

Detach from the process.

fn kill(&self, _pid: Option<u64>) -> Result<(), Error>

Kill the indicated process. If no process is given, then the precise effect is unspecified; but killing any or all processes, or even rebooting an entire bare-metal target, would be appropriate.

fn ping_thread(&self, _id: ThreadId) -> Result<(), Error>

Check whether the indicated thread is alive. If alive, return (). Otherwise, return an error.

fn read_memory(&self, _region: MemoryRegion) -> Result<Vec<u8>, Error>

Read a memory region.

fn write_memory(&self, _address: u64, _bytes: &[u8]) -> Result<(), Error>

Write the provided bytes to memory at the given address.

fn read_register(&self, _register: u64) -> Result<Vec<u8>, Error>

Read the contents of the indicated register. The results should be in target byte order. Note that a value-based API is not provided here because on some architectures, there are registers wider than ordinary integer types.

fn write_register(&self, _register: u64, _contents: &[u8]) -> Result<(), Error>

Set the contents of the indicated register to the given contents. The contents are in target byte order. Note that a value-based API is not provided here because on some architectures, there are registers wider than ordinary integer types.

fn read_general_registers(&self) -> Result<Vec<u8>, Error>

Return the general registers. The registers are returned as a vector of bytes, with the registers appearing contiguously in a target-specific order, with the bytes laid out in the target byte order.

fn write_general_registers(&self, _contents: &[u8]) -> Result<(), Error>

Write the general registers. The registers are specified as a vector of bytes, with the registers appearing contiguously in a target-specific order, with the bytes laid out in the target byte order.

fn read_bytes( &self, _object: String, _annex: String, _offset: u64, _length: u64, ) -> Result<(Vec<u8>, bool), Error>

Read raw bytes from an object, such as “target.xml”. See https://sourceware.org/gdb/onlinedocs/gdb/General-Query-Packets.html#qXfer-read, which describes which kinds of qXfer packets are available.

Return (buffer, eof), a tuple containing the read bytes (at most of size length), if any, and also a boolean specifying whether or not you’re at the end (true = end of file, false = there’s more to read).

If you’re unsure of what to do, follow the rule eof = buffer.is_empty(). You’re allowed to lie about EOF when you’re at the end, GDB will just send one extra command asking for data, where you must disappoint it by admitting you lied.

fn current_thread(&self) -> Result<Option<ThreadId>, Error>

Return the identifier of the current thread.

fn set_current_thread( &self, _for: SetThreadFor, _id: ThreadId, ) -> Result<(), Error>

Set the current thread for future operations.

fn search_memory( &self, _address: u64, _length: u64, _bytes: &[u8], ) -> Result<Option<u64>, Error>

Search memory. The search begins at the given address, and ends after length bytes have been searched. If the provided bytes are not seen, None should be returned; otherwise, the address at which the bytes were found should be returned.

fn invoke(&self, _: &[u8]) -> Result<String, Error>

Invoke a command. The command is just a sequence of bytes (typically ASCII characters), to be interpreted by the server in any way it likes. The result is output to send back to the client. This is used to implement gdb’s monitor command.

fn set_address_randomization(&self, _enable: bool) -> Result<(), Error>

Enable or disable address space randomization. This setting should be used when launching a new process.

fn catch_syscalls(&self, _syscalls: Option<Vec<u64>>) -> Result<(), Error>

Start or stop catching syscalls. If the argument is None, then stop catching syscalls. Otherwise, start catching syscalls. If any syscalls are specified, then only those need be caught; however, it is ok to report syscall stops that aren’t in the list if that is convenient.

fn set_pass_signals(&self, _signals: Vec<u64>) -> Result<(), Error>

Set the list of “pass signals”. A signal marked as a pass signal can be delivered to the inferior. No stopping or notification of the client is required.

fn set_program_signals(&self, _signals: Vec<u64>) -> Result<(), Error>

Set the list of “program signals”. A signal marked as a program signal can be delivered to the inferior; other signals should be silently discarded.

fn thread_info(&self, _thread: ThreadId) -> Result<String, Error>

Return information about a given thread. The returned information is just a string description that can be presented to the user.

fn thread_list(&self, _reset: bool) -> Result<Vec<ThreadId>, Error>

Return a list of all active thread IDs. GDB will call this in a paging fashion: First query has reset set to true and should reply with the first chunk of threads. Further queries have reset set to false and should respond with a chunk of remaining threads, until completion which should return an empty list to signify it’s the end.

Each initial GDB connection will query this and the very first thread ID will be stopped - so ensure the first ID is ready to be stopped and inspected by GDB.

fn insert_software_breakpoint( &self, _breakpoint: Breakpoint, ) -> Result<(), Error>

Insert a software breakpoint.

fn insert_hardware_breakpoint( &self, _breakpoint: Breakpoint, ) -> Result<(), Error>

Insert a hardware breakpoint.

fn insert_write_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Insert a write watchpoint.

fn insert_read_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Insert a read watchpoint.

fn insert_access_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Insert an access watchpoint.

fn remove_software_breakpoint( &self, _breakpoint: Breakpoint, ) -> Result<(), Error>

Remove a software breakpoint.

fn remove_hardware_breakpoint( &self, _breakpoint: Breakpoint, ) -> Result<(), Error>

Remove a hardware breakpoint.

fn remove_write_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Remove a write watchpoint.

fn remove_read_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Remove a read watchpoint.

fn remove_access_watchpoint(&self, _watchpoint: Watchpoint) -> Result<(), Error>

Remove an access watchpoint.

fn query_supported_vcont(&self) -> Result<Cow<'static, [VContFeature]>, Error>

Query for a list of supported vCont features.

fn vcont( &self, _request: Vec<(VCont, Option<ThreadId>)>, ) -> Result<StopReason, Error>

Resume with different actions for each thread. Choose the first matching thread in the list.

fn fs(&self) -> Result<&dyn FileSystem, ()>

Return a filesystem handle to use for vFile requests.

Dynamic types

The reason this uses a &dyn pointer instead of a generic HostFS type parameter, is that type parameters with default values aren’t stable yet

fn process_symbol( &self, _sym_value: &str, _sym_name: &str, ) -> Result<SymbolLookupResponse, Error>

Notifies about symbol requests.

Implementors