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, unsigned int transport_ids, unsigned int transport_preferred_id)
	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_HANDLER (handle_transport_select)
	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...

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

const char *	get_current_transport_name (void)

static bool	is_transport_id_valid (unsigned int id)

static	OOCD_LIST_HEAD (transport_list)
	List of transports registered in OpenOCD, alphabetically sorted per name. More...

static const char *	transport_deprecated_name (unsigned int id)

static const char *	transport_full_name (unsigned int id)

const char *	transport_name (unsigned int id)

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, unsigned int transport_id)

Variables
static unsigned int	allowed_transports
	Bitmask of transport IDs which the currently selected debug adapter supports. More...

struct command_context *	global_cmd_ctx

static unsigned int	preferred_transport
	Transport ID auto-selected when not specified by the user. More...

static struct transport *	session

static const struct command_registration	transport_commands []

static const struct command_registration	transport_group []

struct {
const char * deprecated_name

const char * full_name

unsigned int id

const char * name

}	transport_names []
	List of transports known to OpenOCD. More...

static bool	transport_single_is_autoselected
	Adapter supports a single transport; it has been auto-selected. 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,
		unsigned int	transport_ids,
		unsigned int	transport_preferred_id
	)

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 149 of file transport.c.

References allowed_transports, ERROR_FAIL, ERROR_OK, IS_PWR_OF_2, LOG_DEBUG, LOG_ERROR, mask, preferred_transport, session, TRANSPORT_DAPDIRECT_JTAG, TRANSPORT_DAPDIRECT_SWD, TRANSPORT_HLA_JTAG, TRANSPORT_HLA_SWD, TRANSPORT_JTAG, transport_name(), transport_select(), transport_single_is_autoselected, TRANSPORT_SWD, and TRANSPORT_VALID_MASK.

Referenced by COMMAND_HANDLER().

◆ COMMAND_HANDLER() [1/3]

COMMAND_HANDLER ( handle_transport_init )

Definition at line 272 of file transport.c.

References allowed_transports, BIT, CMD_CTX, ERROR_FAIL, transport::id, transport::init, LOG_DEBUG, LOG_ERROR, LOG_WARNING, session, transport_full_name(), transport_name(), transport_single_is_autoselected, and TRANSPORT_VALID_MASK.

◆ COMMAND_HANDLER() [2/3]

COMMAND_HANDLER ( handle_transport_list )

Definition at line 295 of file transport.c.

References CMD, CMD_ARGC, command_print(), ERROR_COMMAND_SYNTAX_ERROR, ERROR_OK, transport::id, lh(), list_for_each_entry, name, NULL, and transport_name().

◆ COMMAND_HANDLER() [3/3]

COMMAND_HANDLER ( handle_transport_select )

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 321 of file transport.c.

References allowed_transports, BIT, CMD, CMD_ARGC, CMD_ARGV, CMD_CTX, command_print(), ERROR_COMMAND_SYNTAX_ERROR, ERROR_FAIL, ERROR_OK, transport::id, LOG_WARNING, preferred_transport, session, transport_deprecated_name(), transport_full_name(), transport_name(), transport_select(), transport_single_is_autoselected, and TRANSPORT_VALID_MASK.

◆ 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 252 of file transport.c.

References session.

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

◆ get_current_transport_name()

const char* get_current_transport_name ( void )

Definition at line 258 of file transport.c.

References transport::id, is_transport_id_valid(), NULL, session, and transport_full_name().

Referenced by adapter_assert_reset(), adapter_deassert_reset(), adapter_resets(), and hl_transport_init().

◆ is_transport_id_valid()

static bool is_transport_id_valid ( unsigned int id )

static

Definition at line 113 of file transport.c.

References IS_PWR_OF_2, and TRANSPORT_VALID_MASK.

Referenced by get_current_transport_name(), and transport_register().

◆ OOCD_LIST_HEAD()

static OOCD_LIST_HEAD ( transport_list )

static

List of transports registered in OpenOCD, alphabetically sorted per name.

◆ transport_deprecated_name()

static const char* transport_deprecated_name ( unsigned int id )

static

Definition at line 104 of file transport.c.

References ARRAY_SIZE, NULL, and transport_names.

Referenced by COMMAND_HANDLER().

◆ transport_full_name()

static const char* transport_full_name ( unsigned int id )

static

Definition at line 95 of file transport.c.

References ARRAY_SIZE, NULL, and transport_names.

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

◆ transport_name()

const char* transport_name ( unsigned int id )

Definition at line 86 of file transport.c.

References ARRAY_SIZE, NULL, and transport_names.

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

◆ 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 211 of file transport.c.

References ERROR_FAIL, ERROR_OK, transport::id, transport::init, is_transport_id_valid(), lh(), transport::lh, list_add_tail(), list_for_each_entry, LOG_DEBUG, LOG_ERROR, transport::select, transport_full_name(), and transport_name().

◆ transport_register_commands()

int transport_register_commands ( struct command_context * ctx )

Definition at line 432 of file transport.c.

References NULL, register_commands(), and transport_group.

◆ transport_select()

static int transport_select	(	struct command_context *	ctx,
		unsigned int	transport_id
	)

static

Definition at line 118 of file transport.c.

References ERROR_FAIL, ERROR_OK, transport::id, lh(), list_for_each_entry, LOG_ERROR, transport::select, session, and transport_full_name().

Referenced by allow_transports(), and COMMAND_HANDLER().

Variable Documentation

◆ allowed_transports

unsigned int allowed_transports

static

Bitmask of transport IDs which the currently selected debug adapter supports.

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

Definition at line 71 of file transport.c.

Referenced by allow_transports(), and COMMAND_HANDLER().

◆ deprecated_name

const char* deprecated_name

Definition at line 53 of file transport.c.

◆ full_name

const char* full_name

Definition at line 52 of file transport.c.

Referenced by command_can_run(), COMMAND_HANDLER(), command_new(), get_name(), and register_command().

◆ global_cmd_ctx

struct command_context* global_cmd_ctx

extern

Definition at line 233 of file openocd.c.

Referenced by setup_command_handler().

◆ id

unsigned int id

Definition at line 50 of file transport.c.

◆ name

const char* name

Definition at line 51 of file transport.c.

Referenced by COMMAND_HANDLER().

◆ preferred_transport

unsigned int preferred_transport

static

Transport ID auto-selected when not specified by the user.

Definition at line 76 of file transport.c.

Referenced by allow_transports(), and COMMAND_HANDLER().

◆ session

struct transport* session

static

The transport being used for the current OpenOCD session.

Definition at line 84 of file transport.c.

Referenced by allow_transports(), COMMAND_HANDLER(), get_current_transport(), get_current_transport_name(), 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",
        .handler = handle_transport_select,
        .mode = COMMAND_ANY,
        .help = "Select this session's transport",
        .usage = "[transport_name]",
    },
    COMMAND_REGISTRATION_DONE
}

Definition at line 321 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 321 of file transport.c.

Referenced by transport_register_commands().

◆

const { ... } transport_names[]

Initial value:

= {
    { TRANSPORT_JTAG,           "jtag", "jtag",             NULL,             },
    { TRANSPORT_SWD,            "swd",  "swd",              NULL,             },
    { TRANSPORT_HLA_JTAG,       "jtag", "jtag (hla)",       "hla_jtag",       },
    { TRANSPORT_HLA_SWD,        "swd",  "swd (hla)",        "hla_swd",        },
    { TRANSPORT_DAPDIRECT_JTAG, "jtag", "jtag (dapdirect)", "dapdirect_jtag", },
    { TRANSPORT_DAPDIRECT_SWD,  "swd",  "swd (dapdirect)",  "dapdirect_swd",  },
    { TRANSPORT_SWIM,           "swim", "swim",             NULL,             },
}

List of transports known to OpenOCD.

Referenced by transport_deprecated_name(), transport_full_name(), and transport_name().

◆ transport_single_is_autoselected

bool transport_single_is_autoselected

static

Adapter supports a single transport; it has been auto-selected.

Definition at line 81 of file transport.c.

Referenced by allow_transports(), and COMMAND_HANDLER().

Functions

Variables

Detailed Description

Function Documentation

◆ allow_transports()

◆ COMMAND_HANDLER() [1/3]

◆ COMMAND_HANDLER() [2/3]

◆ COMMAND_HANDLER() [3/3]

◆ get_current_transport()

◆ get_current_transport_name()

◆ is_transport_id_valid()

◆ OOCD_LIST_HEAD()

◆ transport_deprecated_name()

◆ transport_full_name()

◆ transport_name()

◆ transport_register()

◆ transport_register_commands()

◆ transport_select()

Variable Documentation

◆ allowed_transports

◆ deprecated_name

◆ full_name

◆ global_cmd_ctx

◆ id

◆ name

◆ preferred_transport

◆ session

◆ transport_commands

◆ transport_group

◆

◆ transport_single_is_autoselected