OpenOCD
adapter_driver Struct Reference

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

Collaboration diagram for adapter_driver:

Data Fields

const struct command_registrationcommands
 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_opsdap_jtag_ops
 
const struct dap_opsdap_swd_ops
 
int(* init )(void)
 Interface driver must initialize any resources and connect to a JTAG device. More...
 
struct jtag_interfacejtag_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_driverswd_ops
 Low-level SWD APIs. More...
 
const struct swim_driverswim_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
enabledWhether to enable trace
pin_protocolConfigured pin protocol
port_sizeTrace port width for sync mode
trace_freqA pointer to the configured trace frequency; if it points to 0, the adapter driver must write its maximum supported rate there
traceclkin_freqTRACECLKIN frequency provided to the TPIU in Hz
prescalerPointer 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 COMMAND_HANDLER(), and jim_adapter_name().

◆ poll_trace

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

Poll for new trace data.

Parameters
bufA pointer to buffer to store received data
sizeA 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
srst1 to assert SRST, 0 to deassert SRST.
trst1 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
speedThe 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
speedThe desired interface speed setting.
khzOn 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_assertedOn 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: