Infrastructure for specifying and managing the transport protocol used in a given debug or programming session. More...

Include dependency graph for transport.c:

Functions
int	allow_transports (struct command_context ctx, const char const *vector)
	Called by debug adapter drivers, or affiliated Tcl config scripts, to declare the set of transports supported by an adapter. More...

	COMMAND_HANDLER (handle_transport_init)

	COMMAND_HANDLER (handle_transport_list)

	COMMAND_HELPER (transport_list_parse, char ***vector)
	Makes and stores a copy of a set of transports passed as parameters to a command. More...

struct transport *	get_current_transport (void)
	Returns the transport currently being used by this debug or programming session. More...

static int	jim_transport_select (Jim_Interp interp, int argc, Jim_Obj const *argv)
	Implements the Tcl "transport select" command, choosing the transport to be used in this debug session from among the set supported by the debug adapter being used. More...

int	transport_register (struct transport *new_transport)
	Registers a transport. More...

int	transport_register_commands (struct command_context *ctx)

static int	transport_select (struct command_context ctx, const char name)

Variables
static const char const	allowed_transports
	NULL-terminated Vector of names of transports which the currently selected debug adapter supports. More...

struct command_context *	global_cmd_ctx

static struct transport *	session

static const struct command_registration	transport_commands []

static const struct command_registration	transport_group []

static struct transport *	transport_list
	List of transports known to OpenOCD. More...

Detailed Description

Infrastructure for specifying and managing the transport protocol used in a given debug or programming session.

Examples of "debug-capable" transports are JTAG or SWD. Additionally, JTAG supports boundary scan testing.

Examples of "programming-capable" transports include SPI or UART; those are used (often mediated by a ROM bootloader) for ISP style programming, to perform an initial load of code into flash, or sometimes into SRAM. Target code could use "variant" options to decide how to use such protocols. For example, Cortex-M3 cores from TI/Luminary and from NXP use different protocols for for UART or SPI based firmware loading.

As a rule, there are protocols layered on top of the transport. For example, different chip families use JTAG in different ways for debugging. Also, each family that supports programming over a UART link for initial firmware loading tends to define its own messaging and error handling.

Definition in file transport.c.

Function Documentation

◆ allow_transports()

int allow_transports	(	struct command_context *	ctx,
		const char const	vector
	)

Called by debug adapter drivers, or affiliated Tcl config scripts, to declare the set of transports supported by an adapter.

When there is only one member of that set, it is automatically selected.

Definition at line 86 of file transport.c.

References allowed_transports, ERROR_FAIL, ERROR_OK, LOG_ERROR, LOG_INFO, session, and transport_select().

Referenced by COMMAND_HANDLER().

◆ COMMAND_HANDLER() [1/2]

COMMAND_HANDLER ( handle_transport_init )

Definition at line 217 of file transport.c.

References allowed_transports, CMD_CTX, ERROR_FAIL, transport::init, LOG_DEBUG, LOG_ERROR, and session.

◆ COMMAND_HANDLER() [2/2]

COMMAND_HANDLER ( handle_transport_list )

Definition at line 236 of file transport.c.

References CMD, CMD_ARGC, command_print(), ERROR_COMMAND_SYNTAX_ERROR, ERROR_OK, transport::next, and transport_list.

◆ COMMAND_HELPER()

COMMAND_HELPER	(	transport_list_parse	,
		char ***	vector
	)

Makes and stores a copy of a set of transports passed as parameters to a command.

Parameters

vector where the resulting copy is stored, as an argv-style NULL-terminated vector.

Definition at line 176 of file transport.c.

References CMD_ARGC, CMD_ARGV, ERROR_COMMAND_SYNTAX_ERROR, ERROR_FAIL, ERROR_OK, LOG_ERROR, transport::name, transport::next, NULL, and transport_list.

◆ get_current_transport()

struct transport* get_current_transport ( void )

Returns the transport currently being used by this debug or programming session.

Returns: handle to the read-only transport entity.

Definition at line 157 of file transport.c.

References session.

Referenced by adapter_assert_reset(), adapter_deassert_reset(), adapter_resets(), aice_transport_init(), hl_transport_init(), target_create(), transport_is_dapdirect_jtag(), transport_is_dapdirect_swd(), transport_is_hla(), transport_is_jtag(), transport_is_swd(), and transport_is_swim().

◆ jim_transport_select()

static int jim_transport_select	(	Jim_Interp *	interp,
		int	argc,
		Jim_Obj const	argv
	)

static

Implements the Tcl "transport select" command, choosing the transport to be used in this debug session from among the set supported by the debug adapter being used.

Return value is scriptable (allowing "if swd then..." etc).

Definition at line 255 of file transport.c.

References allowed_transports, ERROR_OK, global_cmd_ctx, LOG_ERROR, LOG_INFO, LOG_WARNING, transport::name, session, and transport_select().

◆ transport_register()

int transport_register ( struct transport * new_transport )

Registers a transport.

There are general purpose transports (such as JTAG), as well as relatively proprietary ones which are specific to a given chip (or chip family).

Code implementing a transport needs to register it before it can be selected and then activated. This is a dynamic process, so that chips (and families) can define transports as needed (without needing error-prone static tables).

Parameters

new_transport the transport being registered. On a successful return, this memory is owned by the transport framework.

Returns: ERROR_OK on success, else a fault code.

Definition at line 129 of file transport.c.

References ERROR_FAIL, ERROR_OK, transport::init, LOG_DEBUG, LOG_ERROR, transport::name, transport::next, transport::select, and transport_list.

◆ transport_register_commands()

int transport_register_commands ( struct command_context * ctx )

Definition at line 355 of file transport.c.

References NULL, register_commands(), and transport_group.

Referenced by setup_command_handler().

◆ transport_select()

static int transport_select	(	struct command_context *	ctx,
		const char *	name
	)

static

Definition at line 58 of file transport.c.

References ERROR_FAIL, ERROR_OK, LOG_ERROR, name, transport::next, session, and transport_list.

Referenced by allow_transports(), and jim_transport_select().

Variable Documentation

◆ allowed_transports

const char* const* allowed_transports

static

NULL-terminated Vector of names of transports which the currently selected debug adapter supports.

This is declared by the time that adapter is fully set up.

Definition at line 53 of file transport.c.

Referenced by allow_transports(), COMMAND_HANDLER(), and jim_transport_select().

◆ global_cmd_ctx

struct command_context* global_cmd_ctx

extern

Definition at line 292 of file openocd.c.

Referenced by jim_transport_select(), and setup_command_handler().

◆ session

struct transport* session

static

The transport being used for the current OpenOCD session.

Definition at line 56 of file transport.c.

Referenced by allow_transports(), COMMAND_HANDLER(), get_current_transport(), jim_transport_select(), and transport_select().

◆ transport_commands

const struct command_registration transport_commands[]

static

Initial value:

= {
    {
        .name = "init",
        .handler = handle_transport_init,
        
        .mode = COMMAND_ANY,
        .help = "Initialize this session's transport",
        .usage = ""
    },
    {
        .name = "list",
        .handler = handle_transport_list,
        .mode = COMMAND_ANY,
        .help = "list all built-in transports",
        .usage = ""
    },
    {
        .name = "select",
        .jim_handler = jim_transport_select,
        .mode = COMMAND_ANY,
        .help = "Select this session's transport",
        .usage = "[transport_name]",
    },
    COMMAND_REGISTRATION_DONE
}

Definition at line 255 of file transport.c.

◆ transport_group

const struct command_registration transport_group[]

static

Initial value:

= {
    {
        .name = "transport",
        .mode = COMMAND_ANY,
        .help = "Transport command group",
        .chain = transport_commands,
        .usage = ""
    },
    COMMAND_REGISTRATION_DONE
}

Definition at line 255 of file transport.c.

Referenced by transport_register_commands().

◆ transport_list

struct transport* transport_list

static

List of transports known to OpenOCD.

Definition at line 46 of file transport.c.

Referenced by COMMAND_HANDLER(), COMMAND_HELPER(), transport_register(), and transport_select().

Functions

Variables

Detailed Description

Function Documentation

◆ allow_transports()

◆ COMMAND_HANDLER() [1/2]

◆ COMMAND_HANDLER() [2/2]

◆ COMMAND_HELPER()

◆ get_current_transport()

◆ jim_transport_select()

◆ transport_register()

◆ transport_register_commands()

◆ transport_select()

Variable Documentation

◆ allowed_transports

◆ global_cmd_ctx

◆ session

◆ transport_commands

◆ transport_group

◆ transport_list