winIDEA SDK
isys::CExecutionController Class Reference

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:
isys::WrapperBase

Public Types

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

Public Member Functions

std::string call (const std::string &functionName)
 Calls function on the target. More...
 
std::string call (const std::string &functionName, const iconnect::StrVector &params)
 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...
 
 CExecutionController (std::shared_ptr< ConnectionMgr > connectionMgr)
 Instantiates object. More...
 
CPUStatus getCPUStatus (bool wantStopReason=true)
 Returns execution status of the target. More...
 
::IConnectDebuggetIConnectDebug ()
 Returns the isystem.connect Debug interface. 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...
 
int hotAttach ()
 Hot-attaches to the target. More...
 
int hotDetach ()
 Hot-detaches from the target. 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...
 
int run ()
 Runs the program. More...
 
int run (ETimeoutMode timeoutMode, bool throwOnTimeout=true)
 Runs the program. 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, bool throwOnUnexpectedStop)
 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 runUntilReturn ()
 Runs the program until return. More...
 
int runUntilReturn (ETimeoutMode timeoutMode, bool throwOnTimeout=true)
 Runs the program until return. More...
 
void setBlueBoxTargetConnection (bool isConnected)
 Activates/deactivates BlueBox target connection. More...
 
void setBlueBoxTristateStatus (bool isTristate)
 Sets outputs of BlueBox debug connector to tristate or out mode. More...
 
void setPollingEnabled (bool isEnabled)
 Enables/disables polling of target status in winIDEA. More...
 
int setSlowRun (bool isSlowRun)
 If isSlowRun is set to true, then execution is done by stepping through code on the target. More...
 
int stepHigh (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
 Steps one statement in the source code. More...
 
int stepInst (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
 Executes one machine instruction. More...
 
int stepOverHigh (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
 Steps one statement in the source code, does not enter functions. More...
 
int stepOverInst (ETimeoutMode timeoutMode=TOUT_10s, bool throwOnTimeout=true)
 Executes one machine instruction, does not enter subroutines. More...
 
void stop ()
 Stops the execution. 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

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
connectionMgrclass 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
functionNamename 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
functionNamename of the function to call
paramslist 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
functionNamename of the function to call
param1the 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
functionNamename of the function to call
param1the first function parameter. Numbers should be given as a string.
param2the 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
functionNamename of the function to call
param1the first function parameter. Numbers should be given as a string.
param2the second function parameter. Numbers should be given as a string.
param3the 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
wantStopReasonif 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
memAreamemory space. Definitions for individual CPUs are provided in MemArea.h
addressof 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
functionNamename 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
timeoutModespecifies 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
timeoutModespecifies whether to wait until the target is stopped and how long to wait.
throwOnTimeoutif 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
memAreamemory space. Definitions for individual CPUs are provided in MemArea.h
addressof 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
memAreamemory space. Definitions for individual CPUs are provided in MemArea.h
addressof the memory location
timeoutModespecifies whether to wait until the target is stopped and how long to wait.
throwOnTimeoutif 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
functionNamename 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
functionNamename of the function
timeoutModespecifies whether to wait until the target is stopped and how long to wait. Must not be CExecutionController::TOUT_NONE, or results are unpredictable.
throwOnTimeoutif true, exception is thrown on timeout. If false, check return code to detect timeout.
throwOnUnexpectedStopif 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
functionNamename of the function
timeoutModespecifies whether to wait until the target is stopped and how long to wait.
throwOnTimeoutif 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
timeoutModespecifies whether to wait until the target is stopped and how long to wait.
throwOnTimeoutif 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
isConnectedif 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
isTristateif 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
isEnabledif 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
isSlowRunif 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
FeatureNotImplementedExceptionif slow run is not implemented for the target
IOExceptionif changing of the slow run mode is not possible at that moment
IllegalStateExceptionin 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
timeoutModedefines how log to wait for target stop
throwOnTimeoutif 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
timeoutModedefines how log to wait for target stop
throwOnTimeoutif 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
timeoutModedefines how log to wait for target stop
throwOnTimeoutif 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
timeoutModedefines how log to wait for target stop
throwOnTimeoutif 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
timeoutMstimeout in milliseconds. 0 means infinite timeout
pollingIntervalMstime in milliseconds between two readings of the CPU status
isThrowif 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
timeoutMstimeout in milliseconds. 0 means infinite timeout
pollingIntervalMstime in milliseconds between two readings of the CPU status
isThrowif 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