Description

This class can be used to control the execution of the program on a target.

Methods which start execution have two overloads. The second overload has additional parameter, which specifies wait for stop timeout. Functionally this call is equivalent to calling the first overload and waitUntilStopped(), but the first approach uses less CPU time, because pooling is done at lower levels in winIDEA.

Python example for method call().
Python example for method runUntilFunction().
Python example for methods hotAttach() and hotDetach().

#include <CExecutionController.h>

Inheritance diagram for isys::CExecutionController:

Public Types
enum	ETimeoutMode { TOUT_NONE , TOUT_1s , TOUT_10s , TOUT_100s , TOUT_INF }
	Timeout mode and time. More...

Public Member Functions
	CExecutionController (std::shared_ptr< ConnectionMgr > connectionMgr)
	Instantiates object. More...

::IConnectDebug *	getIConnectDebug ()
	Returns the isystem.connect Debug interface. More...

int	hotAttach ()
	Hot-attaches to the target. More...

int	hotDetach ()
	Hot-detaches from the target. More...

int	run ()
	Runs the program. More...

int	run (ETimeoutMode timeoutMode, bool throwOnTimeout=true)
	Runs the program. More...

int	runUntilReturn ()
	Runs the program until return. More...

int	runUntilReturn (ETimeoutMode timeoutMode, bool throwOnTimeout=true)
	Runs the program until return. More...

int	runUntilAddress (uint8_t memArea, ADDRESS_64 address)
	Runs the program until the address is reached. More...

int	runUntilAddress (uint8_t memArea, ADDRESS_64 address, ETimeoutMode timeoutMode, bool throwOnTimeout=true)
	Runs the program until the address is reached. More...

int	runUntilFunction (const std::string &functionName)
	Runs the program until the start of the function is reached. More...

int	runUntilFunction (const std::string &functionName, ETimeoutMode timeoutMode, bool throwOnTimeout=true)
	Runs the program until the start of the function is reached. More...

int	runUntilFunction (const std::string &functionName, ETimeoutMode timeoutMode, bool throwOnTimeout, bool throwOnUnexpectedStop)
	Runs the program until the start of the function is reached. More...

int	setSlowRun (bool isSlowRun)
	If `isSlowRun` is set to `true`, then execution is done by stepping through code on the target. More...

void	gotoAddress (uint8_t memArea, ADDRESS_64 address)
	Moves execution point to the given address. More...

void	gotoFunction (const std::string &functionName)
	Moves execution point to the start of the given function. More...

void	reset (ETimeoutMode timeoutMode=TOUT_NONE)
	Resets the target. More...

int	resetAndRun ()
	Resets the target. More...

int	resetAndRun (ETimeoutMode timeoutMode)
	Resets the target. More...

void	stop ()
	Stops the execution. More...

int	stepHigh (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
	Steps one statement in the source code. More...

int	stepOverHigh (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
	Steps one statement in the source code, does not enter functions. More...

int	stepInst (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
	Executes one machine instruction. More...

int	stepOverInst (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
	Executes one machine instruction, does not enter subroutines. More...

std::string	call (const std::string &functionName)
	Calls function on the target. More...

std::string	call (const std::string &functionName, const std::string &param1)
	Calls function on the target. More...

std::string	call (const std::string &functionName, const std::string &param1, const std::string &param2)
	Calls function on the target. More...

std::string	call (const std::string &functionName, const std::string &param1, const std::string &param2, const std::string &param3)
	Calls function on the target. More...

std::string	call (const std::string &functionName, const iconnect::StrVector &params)
	Calls function on the target. More...

CPUStatus	getCPUStatus (bool wantStopReason=true)
	Returns execution status of the target. More...

void	setPollingEnabled (bool isEnabled)
	Enables/disables polling of target status in winIDEA. More...

void	setBlueBoxTristateStatus (bool isTristate)
	Sets outputs of BlueBox debug connector to tristate or out mode. More...

void	setBlueBoxTargetConnection (bool isConnected)
	Activates/deactivates BlueBox target connection. More...

bool	waitUntilStopped (int timeoutMs=0, uint32_t pollingIntervalMs=100, bool isThrow=false)
	This method polls CPU status with the given polling interval and returns when CPU is stopped or timeout expires. More...

bool	waitWhileRunning (int timeoutMs, uint32_t pollingIntervalMs=100, bool isThrow=false)
	This method polls CPU status with the given polling interval and returns when CPU is no longer running or timeout expires. More...

Member Enumeration Documentation

◆ ETimeoutMode

enum isys::CExecutionController::ETimeoutMode

Timeout mode and time.

Enumerator
TOUT_NONE	does not wait for stop, returns immediately. The target may still be running, when method returns.
TOUT_1s	waits at most 1 s for stop
TOUT_10s	waits at most 10 s for stop
TOUT_100s	waits at most 100 s for stop
TOUT_INF	waits forever for stop. WARNING: Since winIDEA GUI is blocked during wait, you may have to switch off the debugger if target never stops.

Constructor & Destructor Documentation

◆ CExecutionController()

isys::CExecutionController::CExecutionController ( std::shared_ptr< ConnectionMgr > connectionMgr )

Instantiates object.

Parameters

connectionMgr class which maintains connection to winIDEA. Connection must be established before this call.

Python example: test_hot_attach_detach.py

Member Function Documentation

◆ call() [1/5]

std::string isys::CExecutionController::call ( const std::string & functionName )

Calls function on the target.

Required preconditions:

the code must be downloaded to the target
target must be initialized at least to the point where stack is set up
target/compiler pair must be supported by isystem.connect. Most modern targets and compilers are supported. If this function does not work, check isystem web page or ask iSYSTEM support for current status of supported platforms.
all function parameters must be of primitive types (char, int, float, ...)

Parameters

functionName name of the function to call

Returns: function return value as string. Numbers are also returned as strings. If function is of type void, string 'no type information' is returned.

Python example: test_call.py

◆ call() [2/5]

std::string isys::CExecutionController::call	(	const std::string &	functionName,
		const iconnect::StrVector &	params
	)

Calls function on the target.

See call(const std::string &) for list of preconditions.

Parameters

functionName	name of the function to call
params	list of function parameters. Numbers should be given as strings.

Returns: function return value as string. Numbers are also returned as strings.

Python example: test_call.py

◆ call() [3/5]

std::string isys::CExecutionController::call	(	const std::string &	functionName,
		const std::string &	param1
	)

Calls function on the target.

See call(const std::string &) for list of preconditions.

Parameters

functionName	name of the function to call
param1	the first function parameter. Numbers should be given as a string.

Returns: function return value as string. Numbers are also returned as strings.

Python example: test_call.py

◆ call() [4/5]

std::string isys::CExecutionController::call	(	const std::string &	functionName,
		const std::string &	param1,
		const std::string &	param2
	)

Calls function on the target.

See call(const std::string &) for list of preconditions.

Parameters

functionName	name of the function to call
param1	the first function parameter. Numbers should be given as a string.
param2	the second function parameter. Numbers should be given as a string.

Returns: function return value as string. Numbers are also returned as strings.

Python example: test_call.py

◆ call() [5/5]

std::string isys::CExecutionController::call	(	const std::string &	functionName,
		const std::string &	param1,
		const std::string &	param2,
		const std::string &	param3
	)

Calls function on the target.

See call(const std::string &) for list of preconditions.

Parameters

functionName	name of the function to call
param1	the first function parameter. Numbers should be given as a string.
param2	the second function parameter. Numbers should be given as a string.
param3	the third function parameter. Numbers should be given as a string.

Returns: function return value as string. Numbers are also returned as strings.

Python example: test_call.py

◆ getCPUStatus()

CPUStatus isys::CExecutionController::getCPUStatus ( bool wantStopReason = true )

Returns execution status of the target.

Parameters

wantStopReason if true, stop reason is set in the returned object

Python example: test_get_cpustatus.py

◆ getIConnectDebug()

::IConnectDebug * isys::CExecutionController::getIConnectDebug ( )

Returns the isystem.connect Debug interface.

Use this method only when some functionality of the IConnectDebug interface is not accessible from wrapper classes.

◆ gotoAddress()

void isys::CExecutionController::gotoAddress	(	uint8_t	memArea,
		ADDRESS_64	address
	)

Moves execution point to the given address.

Parameters

memArea	memory space. Definitions for individual CPUs are provided in MemArea.h
address	of the memory location

Python example: test_goto_address.py

◆ gotoFunction()

void isys::CExecutionController::gotoFunction ( const std::string & functionName )

Moves execution point to the start of the given function.

Parameters

functionName name of the function

Python example: test_goto_function.py

◆ hotAttach()

int isys::CExecutionController::hotAttach ( )

Hot-attaches to the target.

Returns: 0 if OK, else it is warning. Exception is thrown in case of error.

Python example: test_hot_attach_detach.py

◆ hotDetach()

int isys::CExecutionController::hotDetach ( )

Hot-detaches from the target.

Returns: 0 if OK, else it is warning. Exception is thrown in case of error.

Python example: test_hot_attach_detach.py

◆ reset()

void isys::CExecutionController::reset ( ETimeoutMode timeoutMode = TOUT_NONE )

Resets the target.

Python example: test_run_until_address.py

◆ resetAndRun() [1/2]

int isys::CExecutionController::resetAndRun ( )

Resets the target.

Returns: S_OK or if operation was executed, but there is a warning (for example license will soon expire), ICONNECT_S_MSG_WARN is returned. In case of error an exception is thrown.

Python example: test_reset_and_run.py

◆ resetAndRun() [2/2]

int isys::CExecutionController::resetAndRun ( ETimeoutMode timeoutMode )

Resets the target.

Parameters

timeoutMode specifies whether to wait until the target is stopped and how long to wait.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_reset_and_run.py

◆ run() [1/2]

int isys::CExecutionController::run ( )

Runs the program.

The function is non-blocking. When it returns, the program might still be running (if it didn't hit a breakpoint, for example). Call getStatus() to check the target state, or one of wait...() methods in this class to wait for non-running state.

Returns: S_OK

Python example: test_run_stop.py

◆ run() [2/2]

int isys::CExecutionController::run	(	ETimeoutMode	timeoutMode,
		bool	throwOnTimeout = `true`
	)

Runs the program.

Parameters

timeoutMode	specifies whether to wait until the target is stopped and how long to wait.
throwOnTimeout	if true, exception is thrown on timeout. If false, check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns S_FALSE when timeout is specified and the target is still running (timeout expired).

◆ runUntilAddress() [1/2]

int isys::CExecutionController::runUntilAddress	(	uint8_t	memArea,
		ADDRESS_64	address
	)

Runs the program until the address is reached.

This method is non-blocking. When it returns, the program might still be running. Call getStatus() or waitUntilStopped() to be sure that the program has stopped (note that the program can also stop for other reasons, for example a breakpoint, so checking an address may also be needed in some cases).

Parameters

memArea	memory space. Definitions for individual CPUs are provided in MemArea.h
address	of the memory location

Returns: S_OK

Python example: test_run_until_address.py

◆ runUntilAddress() [2/2]

int isys::CExecutionController::runUntilAddress	(	uint8_t	memArea,
		ADDRESS_64	address,
		ETimeoutMode	timeoutMode,
		bool	throwOnTimeout = `true`
	)

Runs the program until the address is reached.

Parameters

memArea	memory space. Definitions for individual CPUs are provided in MemArea.h
address	of the memory location
timeoutMode	specifies whether to wait until the target is stopped and how long to wait.
throwOnTimeout	if true, exception is thrown on timeout. If false, check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

◆ runUntilFunction() [1/3]

int isys::CExecutionController::runUntilFunction ( const std::string & functionName )

Runs the program until the start of the function is reached.

This method is non-blocking. When it returns, the program might still be running. Call waitUntilStopped() to be sure that the program has stopped (note that the program can also stop for other reasons, for example a breakpoint, so checking an address may also be needed in some cases).

Parameters

functionName name of the function

Returns: S_OK

Python example: test_run_until_function.py

◆ runUntilFunction() [2/3]

int isys::CExecutionController::runUntilFunction	(	const std::string &	functionName,
		ETimeoutMode	timeoutMode,
		bool	throwOnTimeout,
		bool	throwOnUnexpectedStop
	)

Runs the program until the start of the function is reached.

This method differs from other runUntil...() methods in verification of stop address. If it differs from function address, a status code is returned or IOException is thrown.

Parameters

functionName	name of the function
timeoutMode	specifies whether to wait until the target is stopped and how long to wait. Must not be CExecutionController::TOUT_NONE, or results are unpredictable.
throwOnTimeout	if true, exception is thrown on timeout. If false, check return code to detect timeout.
throwOnUnexpectedStop	if true, and the function is not reached because target stopped for some other reason, an IOException is thrown.

Returns: S_OK if the target is stopped at the specified function. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired). Returns ICONNECT_S_MSG_FAIL when the target is stopped, but not at the specified function.

Python example: test_run_until_function.py

◆ runUntilFunction() [3/3]

int isys::CExecutionController::runUntilFunction	(	const std::string &	functionName,
		ETimeoutMode	timeoutMode,
		bool	throwOnTimeout = `true`
	)

Runs the program until the start of the function is reached.

Note that the program can also stop for other reasons, for example a breakpoint, so checking an address may also be needed in some cases, or call the overload with parameter throwOnUnexpectedStop.

Parameters

functionName	name of the function
timeoutMode	specifies whether to wait until the target is stopped and how long to wait.
throwOnTimeout	if true, exception is thrown on timeout. If false, check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_run_until_function.py

◆ runUntilReturn() [1/2]

int isys::CExecutionController::runUntilReturn ( )

Runs the program until return.

The function is non-blocking. When it returns, the program might still be running. Call getStatus() to check the target state.

Returns: S_OK

Python example: test_run_until_return.py

◆ runUntilReturn() [2/2]

int isys::CExecutionController::runUntilReturn	(	ETimeoutMode	timeoutMode,
		bool	throwOnTimeout = `true`
	)

Runs the program until return.

Parameters

timeoutMode	specifies whether to wait until the target is stopped and how long to wait.
throwOnTimeout	if true, exception is thrown on timeout. If false, check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_run_until_function.py

◆ setBlueBoxTargetConnection()

void isys::CExecutionController::setBlueBoxTargetConnection ( bool isConnected )

Activates/deactivates BlueBox target connection.

Parameters

isConnected if true, the debugger is connected to the target

Python example: test_set_blue_box_target_connection.py

◆ setBlueBoxTristateStatus()

void isys::CExecutionController::setBlueBoxTristateStatus ( bool isTristate )

Sets outputs of BlueBox debug connector to tristate or out mode.

Parameters

isTristate if true, outputs are set to tristate

Python example: test_set_blue_box_tristate_status.py

◆ setPollingEnabled()

void isys::CExecutionController::setPollingEnabled ( bool isEnabled )

Enables/disables polling of target status in winIDEA.

Parameters

isEnabled if true, polling is enabled

Python example: test_set_polling_enabled.py

◆ setSlowRun()

int isys::CExecutionController::setSlowRun ( bool isSlowRun )

If isSlowRun is set to true, then execution is done by stepping through code on the target.

This mode enables usage of analyzer on targets without trace capabilities.

Note: This method must be called BEFORE analyzer is started!

Parameters

isSlowRun if true, slow run is enabled, if false, normal run is used

Returns: S_OK if mode is changed, S_FALSE if mode was already set

Exceptions

FeatureNotImplementedException	if slow run is not implemented for the target
IOException	if changing of the slow run mode is not possible at that moment
IllegalStateException	in case of other errors

Python example: test_set_slow_run.py

◆ stepHigh()

int isys::CExecutionController::stepHigh	(	ETimeoutMode	timeoutMode = `TOUT_10s`,
		bool	throwOnTimeout = `true`
	)

Steps one statement in the source code.

Enters functions.

Parameters

timeoutMode	defines how log to wait for target stop
throwOnTimeout	if true, exception is thrown on timeout. If false, caller should check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_step_high.py

◆ stepInst()

int isys::CExecutionController::stepInst	(	ETimeoutMode	timeoutMode = `TOUT_10s`,
		bool	throwOnTimeout = `true`
	)

Executes one machine instruction.

Enters subroutines.

Parameters

timeoutMode	defines how log to wait for target stop
throwOnTimeout	if true, exception is thrown on timeout. If false, caller should check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_step_inst.py

◆ stepOverHigh()

int isys::CExecutionController::stepOverHigh	(	ETimeoutMode	timeoutMode = `TOUT_10s`,
		bool	throwOnTimeout = `true`
	)

Steps one statement in the source code, does not enter functions.

Parameters

timeoutMode	defines how log to wait for target stop
throwOnTimeout	if true, exception is thrown on timeout. If false, caller should check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_step_over_high.py

◆ stepOverInst()

int isys::CExecutionController::stepOverInst	(	ETimeoutMode	timeoutMode = `TOUT_10s`,
		bool	throwOnTimeout = `true`
	)

Executes one machine instruction, does not enter subroutines.

Parameters

timeoutMode	defines how log to wait for target stop
throwOnTimeout	if true, exception is thrown on timeout. If false, caller should check return code to detect timeout.

Returns: S_OK if timeoutMode == CExecutionController::TOUT_NONE, or when the target is stopped. Returns ICONNECT_E_TIMEOUT when timeout is specified and the target is still running (timeout expired).

Python example: test_step_over_inst.py

◆ stop()

void isys::CExecutionController::stop ( )

Stops the execution.

Python example: test_run_stop.py

◆ waitUntilStopped()

bool isys::CExecutionController::waitUntilStopped	(	int	timeoutMs = `0`,
		uint32_t	pollingIntervalMs = `100`,
		bool	isThrow = `false`
	)

This method polls CPU status with the given polling interval and returns when CPU is stopped or timeout expires.

This method waits if CPU is in any other state than stopped state, for example running, halted, must init, ...

Parameters

timeoutMs	timeout in milliseconds. 0 means infinite timeout
pollingIntervalMs	time in milliseconds between two readings of the CPU status
isThrow	if true and timeout occurs, an exception is thrown

Returns: true if CPU is in stopped state, false if timeout expired and isThrow == false

Python example: test_control.py

◆ waitWhileRunning()

bool isys::CExecutionController::waitWhileRunning	(	int	timeoutMs,
		uint32_t	pollingIntervalMs = `100`,
		bool	isThrow = `false`
	)

This method polls CPU status with the given polling interval and returns when CPU is no longer running or timeout expires.

The difference to waitUntilStopped() method is that waitUntilStopped() expects exactly stopped state to return - it won't return on must init state, for example. waitWhileRunning() method will wait only if the target is in running state - it will return on any other state, for example stopped, must init, halted, ...

Parameters

timeoutMs	timeout in milliseconds. 0 means infinite timeout
pollingIntervalMs	time in milliseconds between two readings of the CPU status
isThrow	if true and timeout occurs, an exception is thrown

Returns: true if CPU is not running, false if timeout expired and isThrow == false

Python example: test_wait_state.py

Description

Public Types

Public Member Functions

Member Enumeration Documentation

◆ ETimeoutMode

Constructor & Destructor Documentation

◆ CExecutionController()

Member Function Documentation

◆ call() [1/5]

◆ call() [2/5]

◆ call() [3/5]

◆ call() [4/5]

◆ call() [5/5]

◆ getCPUStatus()

◆ getIConnectDebug()

◆ gotoAddress()

◆ gotoFunction()

◆ hotAttach()

◆ hotDetach()

◆ reset()

◆ resetAndRun() [1/2]

◆ resetAndRun() [2/2]

◆ run() [1/2]

◆ run() [2/2]

◆ runUntilAddress() [1/2]

◆ runUntilAddress() [2/2]

◆ runUntilFunction() [1/3]

◆ runUntilFunction() [2/3]

◆ runUntilFunction() [3/3]

◆ runUntilReturn() [1/2]

◆ runUntilReturn() [2/2]

◆ setBlueBoxTargetConnection()

◆ setBlueBoxTristateStatus()

◆ setPollingEnabled()

◆ setSlowRun()

◆ stepHigh()

◆ stepInst()

◆ stepOverHigh()

◆ stepOverInst()

◆ stop()

◆ waitUntilStopped()

◆ waitWhileRunning()