Represents a driver for a debugging interface. More...

Collaboration diagram for adapter_driver:

Data Fields
const struct command_registration *	commands
	The interface driver may register additional commands to expose additional features not covered by the standard command set. More...

int(*	config_trace )(bool enabled, enum tpiu_pin_protocol pin_protocol, uint32_t port_size, unsigned int trace_freq, unsigned int traceclkin_freq, uint16_t prescaler)
	Configure trace parameters for the adapter. More...

const struct dap_ops *	dap_jtag_ops

const struct dap_ops *	dap_swd_ops

int(*	init )(void)
	Interface driver must initialize any resources and connect to a JTAG device. More...

struct jtag_interface *	jtag_ops
	Low-level JTAG APIs. More...

int(*	khz )(int khz, int *jtag_speed)
	Returns JTAG maximum speed for KHz. More...

const char *const	name
	The name of the interface driver. More...

int(*	poll_trace )(uint8_t buf, size_t size)
	Poll for new trace data. More...

int(*	power_dropout )(int *power_dropout)
	Read and clear the power dropout flag. More...

int(*	quit )(void)
	Interface driver must tear down all resources and disconnect from the JTAG device. More...

int(*	reset )(int srst, int trst)
	Control (assert/deassert) the signals SRST and TRST on the interface. More...

int(*	speed )(int speed)
	Set the interface speed. More...

int(*	speed_div )(int speed, int *khz)
	Calculate the clock frequency (in KHz) for the given speed. More...

int(*	srst_asserted )(int *srst_asserted)
	Read and clear the srst asserted detection flag. More...

const struct swd_driver *	swd_ops
	Low-level SWD APIs. More...

const struct swim_driver *	swim_ops

const char const	transports
	transports supported in C code (NULL terminated vector) More...

Detailed Description

Represents a driver for a debugging interface.

Todo:: We need a per-instance structure too, and changes to pass that structure to the driver. Instances can for example be in either SWD or JTAG modes. This will help remove globals, and eventually to cope with systems which have more than one such debugging interface.

Definition at line 207 of file interface.h.

Field Documentation

◆ commands

const struct command_registration* adapter_driver::commands

The interface driver may register additional commands to expose additional features not covered by the standard command set.

Definition at line 218 of file interface.h.

◆ config_trace

int(* adapter_driver::config_trace) (bool enabled, enum tpiu_pin_protocol pin_protocol, uint32_t port_size, unsigned int *trace_freq, unsigned int traceclkin_freq, uint16_t *prescaler)

Configure trace parameters for the adapter.

Parameters

enabled	Whether to enable trace
pin_protocol	Configured pin protocol
port_size	Trace port width for sync mode
trace_freq	A pointer to the configured trace frequency; if it points to 0, the adapter driver must write its maximum supported rate there
traceclkin_freq	TRACECLKIN frequency provided to the TPIU in Hz
prescaler	Pointer to the SWO prescaler calculated by the adapter

Returns: ERROR_OK on success, an error code on failure.

Definition at line 326 of file interface.h.

Referenced by adapter_config_trace().

◆ dap_jtag_ops

const struct dap_ops* adapter_driver::dap_jtag_ops

Definition at line 348 of file interface.h.

Referenced by dap_init_all().

◆ dap_swd_ops

const struct dap_ops* adapter_driver::dap_swd_ops

Definition at line 351 of file interface.h.

Referenced by dap_init_all().

◆ init

int(* adapter_driver::init) (void)

Interface driver must initialize any resources and connect to a JTAG device.

quit() is invoked if and only if init() succeeds. quit() is always invoked if init() succeeds. Same as malloc() + free(). Always invoke free() if malloc() succeeds and do not invoke free() otherwise.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 231 of file interface.h.

Referenced by adapter_init().

◆ jtag_ops

struct jtag_interface* adapter_driver::jtag_ops

Low-level JTAG APIs.

Definition at line 342 of file interface.h.

Referenced by default_interface_jtag_execute_queue(), and jtag_add_tms_seq().

◆ khz

int(* adapter_driver::khz) (int khz, int *jtag_speed)

Returns JTAG maximum speed for KHz.

0 = RTCK. The function returns a failure if it can't support the KHz/RTCK.

WARNING!!!! if RTCK is slow then think carefully about whether you actually want to support this in the driver. Many target scripts are written to handle the absence of RTCK and use a fallback kHz TCK.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 274 of file interface.h.

Referenced by adapter_khz_to_speed().

◆ name

const char* const adapter_driver::name

The name of the interface driver.

Definition at line 209 of file interface.h.

Referenced by adapter_init(), and COMMAND_HANDLER().

◆ poll_trace

int(* adapter_driver::poll_trace) (uint8_t *buf, size_t *size)

Poll for new trace data.

Parameters

buf	A pointer to buffer to store received data
size	A pointer to buffer size; must be filled with the actual amount of bytes written

Returns: ERROR_OK on success, an error code on failure.

Definition at line 339 of file interface.h.

Referenced by adapter_poll_trace().

◆ power_dropout

int(* adapter_driver::power_dropout) (int *power_dropout)

Read and clear the power dropout flag.

Note that a power dropout can be transitionary, easily much less than a ms.

To find out if the power is currently on, one must invoke this method twice. Once to clear the power dropout flag and a second time to read the current state. The default implementation never reports power dropouts.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 296 of file interface.h.

Referenced by jtag_power_dropout().

◆ quit

int(* adapter_driver::quit) (void)

Interface driver must tear down all resources and disconnect from the JTAG device.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 239 of file interface.h.

Referenced by adapter_quit().

◆ reset

int(* adapter_driver::reset) (int srst, int trst)

Control (assert/deassert) the signals SRST and TRST on the interface.

This function is synchronous and should be called after the adapter queue has been properly flushed. This function is optional. Adapters that don't support resets can either not define this function or return an error code. Adapters that don't support one of the two reset should ignore the request to assert the missing signal and eventually log an error.

Parameters

srst	1 to assert SRST, 0 to deassert SRST.
trst	1 to assert TRST, 0 to deassert TRST.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 255 of file interface.h.

Referenced by adapter_system_reset(), and jtag_add_reset().

◆ speed

int(* adapter_driver::speed) (int speed)

Set the interface speed.

Parameters

speed The new interface speed setting.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 262 of file interface.h.

Referenced by adapter_init(), adapter_set_speed(), and stm8_init().

◆ speed_div

int(* adapter_driver::speed_div) (int speed, int *khz)

Calculate the clock frequency (in KHz) for the given speed.

Parameters

speed	The desired interface speed setting.
khz	On return, contains the speed in KHz (0 for RTCK).

Returns: ERROR_OK on success, or an error code if the interface cannot support the specified speed (KHz or RTCK).

Definition at line 283 of file interface.h.

Referenced by adapter_get_speed_readable().

◆ srst_asserted

int(* adapter_driver::srst_asserted) (int *srst_asserted)

Read and clear the srst asserted detection flag.

Like power_dropout this does not read the current state. SRST assertion is transitionary and may be much less than 1ms, so the interface driver must watch for these events until this routine is called.

Parameters

srst_asserted On return, indicates whether SRST has been asserted.

Returns: ERROR_OK on success, or an error code on failure.

Definition at line 310 of file interface.h.

Referenced by jtag_get_reset_config().

◆ swd_ops

const struct swd_driver* adapter_driver::swd_ops

Low-level SWD APIs.

Definition at line 345 of file interface.h.

Referenced by dap_init_all(), and swd_select().

◆ swim_ops

const struct swim_driver* adapter_driver::swim_ops

Definition at line 354 of file interface.h.

Referenced by swim_read_mem(), swim_reconnect(), swim_system_reset(), and swim_write_mem().

◆ transports

const char* const* adapter_driver::transports

transports supported in C code (NULL terminated vector)

Definition at line 212 of file interface.h.

Referenced by COMMAND_HANDLER().

The documentation for this struct was generated from the following file:

interface.h

Data Fields

Detailed Description

Field Documentation

◆ commands

◆ config_trace

◆ dap_jtag_ops

◆ dap_swd_ops

◆ init

◆ jtag_ops

◆ khz

◆ name

◆ poll_trace

◆ power_dropout

◆ quit

◆ reset

◆ speed

◆ speed_div

◆ srst_asserted

◆ swd_ops

◆ swim_ops

◆ transports