winIDEA SDK
isys::CSessionCtrl Class Reference

Description

This class provides debug session function.

#include <CSessionCtrl.h>

Inherits isys::CSessionBaseCtrl, and std::enable_shared_from_this< CSessionCtrl >.

Public Member Functions

void begin_attach ()
 Starts a new debug session and attaches to all System on Chips (SoCs) that are configured to attach on session start. More...
 
void begin_prepare ()
 Initializes a new debug session without attaching to any SoC. More...
 
void begin_program ()
 Initializes a new debug session, starts emulation (HAR) on all SoCs, and programs them with the target code. More...
 
void begin_reset ()
 Initializes a new debug session and starts emulation (HAR) on all System on Chips (SoCs). More...
 
void end ()
 Ends debug session (detaches from all SoCs). More...
 
std::vector< SPSessionTopology_CoreBindingget_core_SMP_bindings (uint32_t dwSoCIndex=0) const
 Retrieves a union of SMP and non-SMP core bindings for the specified SoC (System on Chip). More...
 
SPProcessCtrl get_process (const std::string &strProcessURL)
 Retrieves a control object for the specified process. More...
 
SPSoCCtrl get_SoC (const std::string &strSoC)
 Retrieves a control object for the specified System on Chip (SoC). More...
 
SPSessionStatus get_status ()
 Returns the current state of the debug session. More...
 
SPTerminalCtrl get_terminal (std::string strConfiguration="")
 Retrieves a control object for the specified terminal configuration. More...
 
SPSessionTopology get_topology ()
 Retrieves the current session topology, including attached SoCs (Systems on Chips) and their associated processes. More...
 
SPConnectionMgr instance_attach (const std::string &strName)
 Attaches to a specified instance by its name and returns the corresponding connection manager. More...
 
SPConnectionMgr instance_attach (uint32_t dwCoreIndex)
 Attaches to a specified instance by its name and returns the corresponding connection manager. More...
 
bool instance_is_attached (uint32_t dwCoreIndex) const
 Checks if the winIDEA instance controlling the specified core index is currently attached. More...
 
std::string process_attach ()
 Attaches to the specified process, loads its symbol files, and creates a working image. More...
 
void process_focus (const std::string &strProcessURL)
 Focuses on the specified process by its URL. More...
 
void program_verify ()
 Performs post-download verification to ensure data integrity and correctness. More...
 

Member Function Documentation

◆ begin_attach()

void isys::CSessionCtrl::begin_attach ( )

Starts a new debug session and attaches to all System on Chips (SoCs) that are configured to attach on session start.

This method connects to an already running target without resetting or programming it.

Exceptions
TExceptionif session initialization fails, which can occur due to connection issues, incorrect configuration, or other hardware-related problems.

Python example: test_get_process.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_attach()
>>> sess_ctrl.get_status().SoCs()[0].status_string()
'ATTACHED'

◆ begin_prepare()

void isys::CSessionCtrl::begin_prepare ( )

Initializes a new debug session without attaching to any SoC.

This method sets up the Blue Box and the debug session, stopping just before any interaction with the target hardware. It allows you to prepare the environment without affecting the target.

Exceptions
TExceptionif session initialization fails, which can occur due to connection issues, incorrect configuration, or other hardware-related problems.

Python example: test_begin_prepare.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()
>>> sess_ctrl.get_status().SoCs()[0].status_string()
'DETACHED'

◆ begin_program()

void isys::CSessionCtrl::begin_program ( )

Initializes a new debug session, starts emulation (HAR) on all SoCs, and programs them with the target code.

In simpler terms, this method downloads the executable code to the target SoCs and halts execution at the reset vector

Exceptions
TExceptionif the session initialization or code programming fails. This may occur due to connection issues, target misconfiguration, or other internal errors during the initialization process.

Python example: test_begin_program.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_program()
>>> sess_ctrl.get_status().SoCs()[0].status_string()
'ATTACHED'

◆ begin_reset()

void isys::CSessionCtrl::begin_reset ( )

Initializes a new debug session and starts emulation (HAR) on all System on Chips (SoCs).

Specifically, this method resets the target SoCs and halts execution at the reset vector, without performing any code programming.

Exceptions
TExceptionif the session initialization or code programming fails. This may occur due to connection issues, target misconfiguration, or other internal errors during the initialization process.

Python example: test_soc_ctrl_attach.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_reset()
>>> sess_ctrl.get_status().SoCs()[0].status_string()
'ATTACHED'

◆ end()

void isys::CSessionCtrl::end ( )

Ends debug session (detaches from all SoCs).

Python example: test_begin_prepare.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()
>>> sess_strl.end()
>>> len(sess_ctrl.get_status().SoCs())
0

◆ get_core_SMP_bindings()

std::vector< SPSessionTopology_CoreBinding > isys::CSessionCtrl::get_core_SMP_bindings ( uint32_t  dwSoCIndex = 0) const

Retrieves a union of SMP and non-SMP core bindings for the specified SoC (System on Chip).

For non-SMP cores, the binding will reference the core's name and its core index. SMP cores will be included as part of the union, representing all cores in the SMP group.

Parameters
dwSoCIndexThe index of the SoC for which core bindings should be retrieved. Defaults to 0 if no index is provided.
Returns
std::vector<SPSessionTopology_CoreBinding> A vector containing the core bindings for both SMP and non-SMP cores within the specified SoC.

◆ get_process()

SPProcessCtrl isys::CSessionCtrl::get_process ( const std::string &  strProcessURL)

Retrieves a control object for the specified process.

This method returns a CProcessCtrl instance that provides control over the process identified by the given URL. The process URL should match one of the processes listed in the session topology. This control object allows you to interact with and manage the specified process.

Parameters
strProcessURLThe URL of the process to retrieve. This URL should be obtained from the session's topology and must correspond to a valid process.
Returns
SPProcessCtrl smart pointer to the control object for the specified process.
Exceptions
TExceptionIf the process cannot be found or the operation fails.

Python example: test_get_process.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_attach()
>>> sess_ctrl.get_topology().processes()[0].URL()
'App/CORE0' 
>>> type(sess_ctrl.get_process('App/CORE0'))
<class 'isystem.connect.CProcessCtrl'>

◆ get_SoC()

SPSoCCtrl isys::CSessionCtrl::get_SoC ( const std::string &  strSoC)

Retrieves a control object for the specified System on Chip (SoC).

This method returns a CSoCCtrl instance that provides control over the SoC identified by the given name. The session must be active, which means it should have been started with one of the begin_ methods such as begin_attach or begin_program.

Parameters
strSoCThe name of the SoC as configured in winIDEA. If only one SoC is used in the session, this string can be left empty to retrieve the default SoC.
Returns
SPSoCCtrl smart pointer to the control object for the specified SoC.
Exceptions
TExceptionIf the session is not active or the SoC cannot be found.

Python example: test_get_soc.py

>>> conn_mgr = ic.ConnectionMgr()
>>> conn_mgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(conn_mgr)
>>> sess_ctrl.begin_attach()
>>> soc_ctrl = sess_ctrl.get_SoC('')
>>> type(soc_ctrl)
<class 'isystem.connect.CSoCCtrl'>

◆ get_status()

SPSessionStatus isys::CSessionCtrl::get_status ( )

Returns the current state of the debug session.

This method returns the session's status, including information about connected SoCs, their states, and other relevant details.

Exceptions
TExceptionif the session status cannot be obtained, which may occur due to connection or other issues.

>>> cmgr = ic.ConnectionMgr() >>> cmgr.connect() >>> sess_ctrl = ic.CSessionCtrl(cmgr) >>> sess_ctrl.begin_prepare() >>> sess_ctrl.get_status().SoCs()[0].status_string() 'DETACHED'

◆ get_terminal()

SPTerminalCtrl isys::CSessionCtrl::get_terminal ( std::string  strConfiguration = "")

Retrieves a control object for the specified terminal configuration.

This method returns an CTerminalCtrl instance that provides control over the terminal specified by the given configuration name. If the configuration name is empty, it retrieves the control object for the default or first terminal configuration.

Parameters
strConfigurationThe name of the terminal configuration to retrieve. If this string is empty, the method returns the control object for the default terminal configuration.
Returns
SPTerminalCtrl smart pointer to the control object for the specified terminal.
Exceptions
TExceptionIf the terminal configuration cannot be found or if the operation fails.

Python example: test_get_terminal.py

>>> conn_mgr = ic.ConnectionMgr()
>>> conn_mgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(conn_mgr)
>>> sess_ctrl.begin_attach()
>>> terminal_ctrl = sess_ctrl.get_terminal('')
>>> type(terminal_ctrl)
<class 'isystem.connect.CTerminalCtrl'>

◆ get_topology()

SPSessionTopology isys::CSessionCtrl::get_topology ( )

Retrieves the current session topology, including attached SoCs (Systems on Chips) and their associated processes.

The session topology provides detailed information about the SoCs, such as their names, devices, and the cores they contain.

Exceptions
TExceptionif the topology information cannot be retrieved, which may occur due to connection issues or if the session is not properly initialized.

Python example: test_get_topology.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()
>>> sess_ctrl.get_topology().SoCs()[0].name()
'MCU'
>>> sess_ctrl.get_topology().SoCs()[0].device()
'STM32F412xG'
>>> sess_ctrl.get_topology().SoCs()[0].cores()[0].name()
'CORE0'

◆ instance_attach() [1/2]

SPConnectionMgr isys::CSessionCtrl::instance_attach ( const std::string &  strName)

Attaches to a specified instance by its name and returns the corresponding connection manager.

If no existing connection is found, this method may launch a new winIDEA instance.

Parameters
strNameThe name of the instance to attach to, as specified in SPSessionTopology_CoreBinding.
Returns
SPConnectionMgr The connection manager for the specified instance.
Exceptions
TExceptionif the provided instance name is invalid or if the attachment process fails.
>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()
>>> sess_ctrl.get_topology().SoCs()[0].cores()[0].name()
'CORE0'
>>> cmgr1 = ses_ctrl.instance_attach('CORE0')
>>> cmgr1.isAttached()
True

◆ instance_attach() [2/2]

SPConnectionMgr isys::CSessionCtrl::instance_attach ( uint32_t  dwCoreIndex)

Attaches to a specified instance by its name and returns the corresponding connection manager.

If no existing connection is found, this method may launch a new winIDEA instance.

Parameters
dwCoreIndexThe index of the instance to attach to, as specified in SPSessionTopology_CoreBinding.
Returns
SPConnectionMgr The connection manager for the specified instance.
Exceptions
TExceptionif the provided instance name is invalid or if the attachment process fails.
>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()
>>> cmgr1 = ses_ctrl.instance_attach(0)
>>> cmgr1.isAttached()
True

◆ instance_is_attached()

bool isys::CSessionCtrl::instance_is_attached ( uint32_t  dwCoreIndex) const

Checks if the winIDEA instance controlling the specified core index is currently attached.

Parameters
dwCoreIndexThe index of the core to check.
Returns
bool True if the instance managing the specified core is attached, false otherwise.
>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_prepare()

◆ process_attach()

std::string isys::CSessionCtrl::process_attach ( )

Attaches to the specified process, loads its symbol files, and creates a working image.

This method establishes a connection to the target process, ensuring that its symbol files are loaded and a working image is created for debugging purposes.

Returns
std::string The URL of the attached process.
Exceptions
TExceptionIf the attachment process fails.

Python example: test_process_attach.py

◆ process_focus()

void isys::CSessionCtrl::process_focus ( const std::string &  strProcessURL)

Focuses on the specified process by its URL.

This method brings the process identified by the provided URL into focus, making it the current target for debugging operations. This is typically used to direct further actions or inspections to the specified process.

Parameters
strProcessURLThe URL of the process to focus. This should be a valid URL as obtained from the process list in the session topology.
Exceptions
TExceptionIf the process cannot be focused, or if an invalid URL is provided.

Python example: test_process_focus.py

>>> cmgr = ic.ConnectionMgr()
>>> cmgr.connect()
>>> sess_ctrl = ic.CSessionCtrl(cmgr)
>>> sess_ctrl.begin_attach()
>>> sess_ctrl.get_topology().processes()[0].URL()
'App/CORE0'
>>> sess_ctrl.process_focus('App/CORE0')

◆ program_verify()

void isys::CSessionCtrl::program_verify ( )

Performs post-download verification to ensure data integrity and correctness.

This function checks the validity of the downloaded data and ensures that it meets expected standards (e.g., checksum verification, completeness).

Exceptions
IOExceptionif the verification process fails due to file read issues or any I/O operation errors.
IllegalStateExceptionif the downloaded data is found to be corrupted or incomplete during the verification process.