fit.interfaces.gdb package

Submodules

fit.interfaces.gdb.boards module

class fit.interfaces.gdb.boards.BoardsFamilies(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration of supported boards families.

STM32 = 1

UNKNOWN = 0

fit.interfaces.gdb.controller module

class fit.interfaces.gdb.controller.GDBController(command)

Bases: object

Class that abstracts GDB MI interactions and provides command writing, response filtering, and graceful shutdown.

await_response(request_response, wait_for, whole_response=False, stop_event=None)

Function that continuously poll responses from GDB until one matches the ‘wait_for’ condition.

Parameters:

• request_response (list[dict[str, Any]]) – the response to poll.

• wait_for (list[dict[str, Any]] | dict[str, Any]) – the expected response pattern.

• whole_response (bool) – if True, return all responses when matched.

Return type:

list[dict[str, Any]]

Returns:

the matching response or full history if requested.

controller: GdbController

exit()

Function that terminates the GDB session.

Return type:

None

flush()

Function that flushes any pending GDB output without action on it

Return type:

None

wait_response(wait_for=None, whole_response=False, stop_event=None)

Function that waits for a response from GDB that matches the specified criteria.

Parameters:

• wait_for (UnionType[list[dict[str, Any]], dict[str, Any], None]) – the expected response pattern.

• whole_response (bool) – if True, return all responses when matched.

Return type:

list[dict[str, Any]]

Returns:

the list of response dictionaries.

write(command, wait_for=None, whole_response=False)

Function that sends a command to GDB and optionally wait for a matching response.

Parameters:

• command (str) – the command string to send.

• wait_for (UnionType[list[dict[str, Any]], dict[str, Any], None]) – the response structure to wait for.

• whole_response (bool) – if True, returns the full response instead of just the match.

Return type:

list[dict[str, Any]]

Returns:

the list of response dictionaries from GDB.

fit.interfaces.gdb.controller.check(data, wait_for)

Function that performs a deep check of the data against the wait_for dictionary. Each specified key must be present in the data. The values just need partial matching to be considered a match. So everything in data must be in wait_for, but not everything in wait_for must be in data.

Parameters:

• data (dict[str, Any]) – the data to check.

• wait_for (dict[str, Any]) – the dictionary to check.

Return type:

bool

Returns:

the result of the check.

fit.interfaces.gdb.gdb_injector module

class fit.interfaces.gdb.gdb_injector.GDBInjector(elf_path, **kwargs)

Bases: InternalInjector

Class that implements the GDB interface of the InternalInjector class.

class Breakpoint(id, address, name)

Bases: object

Class that represents the breakpoint set in the target binary.

address: int

Breakpoint name.

id: int

Breakpoint address.

name: str

class State(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Enumeration class that enums all possible states.

EXIT = 3

INTERRUPT = 2

RUNNING = 1

STARTING = 0

board_family: BoardsFamilies = 0

Endianness of the target architecture.

breakpoints: list[Breakpoint] = []

close()

Function that closes the GDB session and exit the controller.

Return type:

None

controller: GDBController

Path to the GDB executable. Defaults to ‘gdb_multiarch’.

embedded: bool = False

Enum representing known embedded board families.

endianness = 'little'

Word size in bytes.

gdb_path: str = 'gdb_multiarch'

List of available register names.

get_mappings()

Function that retrieves memory mappings using GDB’s ‘info proc mappings’

Return type:

list[Mapping]

Returns:

the list of memory mappings.

get_register_names()

Function that returns a list of registers names.

Return type:

list[str]

Returns:

the list of registers names.

interrupt()

Function that interrupts the running process.

Return type:

Optional[str]

is_running()

Function that checks if the target is running.

Return type:

bool

Returns:

True if the target is running.

read_memory(address, count)

Function that reads a memory word from the target.

Parameters:

• address (int) – the memory address to read from.

• count (int) – the number of bytes to read.

Return type:

list[int]

Returns:

the value read from the target.

read_register(register)

Function that reads a register from the target.

Parameters:

register (str) – the register to read.

Return type:

int

Returns:

the value read from the target.

register_names: list[str]

Indicates if the target is an embedded device.

remote(address)

Function that connects to a remote GDB server.

Parameters:

address (str) – the remote address in ‘host:port’ format.

Return type:

list[dict[str, Any]]

Returns:

the GDB response payload.

reset()

Function that resets the injector to a known initial state. Useful between test runs or injections.

Return type:

None

reset_functions = {BoardsFamilies.STM32: <function GDBInjector.reset_stm32>, BoardsFamilies.UNKNOWN: <function GDBInjector.reset_unknown>}

reset_stm32()

Function that performs a hard reset on the target. This calls the monitor command jtag_reset in the st-util gdb server. Then, since the target is in a reset state, we wait for the DHCSR register to indicate that the target is in a reset state. If the target is not in a reset state, we wait for 0.5 seconds and check again. The library cannot do this on its own because it can’t access the usb device directly since it’s already occupied by _this_ gdb server.

These values _should_ be portable since stlink uses them for everything, so it might be a standard.

Return type:

None

reset_unknown()

Function that perform a soft reset on the target. This calls the monitor command reset in the st-util gdb server.

Return type:

None

run(blocking=False, stop_event=None)

Function that runs the injector for a given amount of time.

Parameters:

blocking (bool) – whether to block until the precess stops.

Return type:

str

Returns:

the name of the breakpoint hit.

set_event(event)

Function that sets a specific event for this target.

Parameters:

event (str) – the event to set.

Return type:

None

state: State = 0

word_size: int = 4

write_memory(address, value, repeat)

Function that writes a memory word from the target.

Parameters:

• address (int) – the memory address to write to.

• value (list[int]) – the value to write.

Return type:

None

write_register(register, value)

Function that writes a register from the target.

Parameters:

• register (str) – the register to write.

• value (int) – the value to write.

Return type:

None

fit.interfaces.gdb.gdb_injector.get_int(s, byteorder)

Function that converts a hex string to an integer.

Parameters:

• s (str) – the hex string to convert.

• byteorder (Literal['little', 'big']) – the endianness of the string (little or big).

Return type:

int

Returns:

the integer value

fit.interfaces.gdb.gdb_injector.parse_memory(memory, count, word_size, endianness)

Return type:

list[int]

fit.interfaces.gdb.gdb_injector.to_gdb_hex(i, byteorder, word_size)

Function that converts an integer to hex string.

Parameters:

• i (list[int]) – the integer to convert.

• byteorder (Literal['little', 'big']) – the endianness of the string (little or big).

Return type:

str

Returns:

the hex string representation of the integer value.

Module contents