Skip to main content
aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to 'docs/TCF Service - Run Control.html')
-rw-r--r--docs/TCF Service - Run Control.html618
1 files changed, 618 insertions, 0 deletions
diff --git a/docs/TCF Service - Run Control.html b/docs/TCF Service - Run Control.html
new file mode 100644
index 000000000..dc17b079b
--- /dev/null
+++ b/docs/TCF Service - Run Control.html
@@ -0,0 +1,618 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - Run Control</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - Run Control</h1>
+
+<ul>
+ <li><a href='#Cmds'>Commands</a>
+ <ul>
+ <li><a href='#CmdGetContext'>Get Context</a>
+ <li><a href='#CmdGetChildren'>Get Children</a>
+ <li><a href='#CmdSuspend'>Suspend</a>
+ <li><a href='#CmdResume'>Resume</a>
+ <li><a href='#CmdGetState'>Get State</a>
+ <li><a href='#CmdTerminate'>Terminate</a>
+ </ul>
+ <li><a href='#Events'>Events</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Run Control Service</h1>
+
+<p>The service provides basic run control operations for execution contexts on a target.
+Command and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p>
+
+<p>The service uses standard format for error reports,
+see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p>
+
+<h2><a name='Cmds'>Commands</a></h2>
+
+<p>All run control commands are fully asynchronous, which means they never wait until
+context is in a particular state. For example, if single step command arrives when
+context is running, it does not wait until it stops, but returns an error. If a command
+successfully resumed a context, it does not wait until instruction pointer reaches
+desired destination from client point of view the command execution ends right after
+context was resumed. Various stepping commands can leave a context running in a special
+mode, which is different from normal execution, for example, it can leave temporary
+breakpoints to suspend the context when control reaches a particular place. Such execution
+mode ends when the context is suspended, even if it was suspended for reasons unrelated
+to the command and intended destination was not reached. Client can know when and
+why a context is suspended by listening to events.</p>
+
+<h3><a name='CmdGetContext'>Get Context</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl getContext <i>&lt;string: context ID&gt;</i>
+</font></b></pre>
+
+<p>The command retrieves context properties for given context ID.
+Exact meaning of context depends on the target.
+A context can represent an execution thread, a process, an address space, etc.
+A context can belong to a parent context. Contexts hierarchy can be simple
+plain list or it can form a tree. It is up to target agent developers to choose
+layout that is most descriptive for a given target. Context IDs are valid across
+all services. In other words, all services access same hierarchy of contexts,
+with same IDs, however, each service accesses its own subset of context's
+attributes and functionality, which is relevant to that service.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i> <i>&lt;context data&gt;</i>
+
+<i>&lt;context data&gt;</i>
+ <font face=Wingdings></font> null
+ <font face=Wingdings></font> <i>&lt;object: context properties&gt;</i>
+</font></b></pre>
+
+<p>Context data object is collection of context properties. It should, at least, contain member
+<b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b>.
+It can also contain arbitrary number of components
+describing context properties and capabilities. Context data is supposed to be cached
+by clients and it is not expected to change frequently. It can include, for example,
+context name or ability to perform single step command on the context. But, it should
+not include volatile data like current PC or running/suspended state. Service sends
+contextChanged event to notify changes in context data.</p>
+
+<p>Predefined run control context properties are:</p>
+<ul>
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of the context, same as getContext command argument.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i>&lt;string&gt;</i></font></b></code>
+ - ID of a parent context.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"IsContainer" : <i>&lt;boolean&gt;</i></font></b></code>
+ - true if the context is a container.
+ Executing resume or suspend command on a container causes all its children to resume or suspend.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"HasState" : <i>&lt;boolean&gt;</i></font></b></code>
+ - true if the context is an execution context, therefore
+ has an execution state, like state of a program counter (PC).
+ Only context that has a state can be resumed or suspended.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"CanSuspend" : <i>&lt;boolean&gt;</i></font></b></code>
+ - true if Suspend command is supported for this contex. It does not mean that the command can be executed successfully in
+ the current state of the context. For example, the command still can fail if context is already suspended.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"CanResume" : <i>&lt;int: bitset of resume modes&gt;</i></font></b></code>
+ - for each resume mode, corresponding bit is '1' if Resume command mode is supported for this contex, and '0' otherwise.
+ It does not mean that the command can be executed successfully in
+ the current state of the context. For example, the command still can fail if context is already resumed.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"CanCount" : <i>&lt;int: bitset of resume modes&gt;</i></font></b></code>
+ - for each resume mode, corresponding bit is '1' if Resume command mode with count other then 1 is supported by the context.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"CanTerminate" : <i>&lt;boolean&gt;</i></font></b></code>
+ - true if Terminate command is supported by the context,
+</ul>
+
+<h3><a name='CmdGetChildren'>Get Children</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl getChildren <i>&lt;string: parent context ID&gt;</i>
+</font></b></pre>
+
+<p>The command requests list of execution contexts available for run control commands.</p>
+
+<p>Parent context ID can be null to retrieve top level of the hierarchy, can be one
+of context IDs retrieved by previous getChildren commands, or it can be obtained from another service.
+Contexts hierarchy can be simple plain list or it can form a tree. It is up to target agent developers to
+choose layout that is most descriptive for a given target.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i> <i>&lt;array of context IDs&gt;</i>
+
+<i>&lt;array of context IDs&gt;</i>
+ <font face=Wingdings></font> null
+ <font face=Wingdings></font> [ <i>&lt;context ID list&gt;</i> ]
+
+<i>&lt;context ID list&gt;</i>
+ <font face=Wingdings></font> <i>&lt;string: context ID&gt;</i>
+ <font face=Wingdings></font> <i>&lt;context ID list&gt;</i> , <i>&lt;string: context ID&gt;</i>
+</font></b></pre>
+
+<h3><a name='CmdSuspend'>Suspend</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl suspend <i>&lt;string: context ID&gt;</i>
+</font></b></pre>
+
+<p>The command suspends execution of given context. The command should fail if CanSuspend property of the context is false.
+If context's IsContainer = true, the command is propagated to context's children. Only contexts with HasState = true
+can be suspended.</p>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i>
+</font></b></pre>
+
+<h3><a name='CmdResume'>Resume</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl resume <i>&lt;string: context ID&gt;</i> <i>&lt;int: mode&gt;</i> <i>&lt;int: count&gt;</i>
+</font></b></pre>
+
+<p>The command resumes execution of given context. The command should fail if CanResume
+property of the context is '0' for given mode. If context's IsContainer = true, the command is propagated
+to context's children. Only contexts with HasState = true can be resumed.</p>
+
+<p>Resume modes:</p>
+<ul>
+ <li><code>RM_RESUME = 0</code> - rusume normal execution. Execution will
+ continue until suspended by command or breakpoint.
+
+ <li><code>RM_STEP_OVER = 1</code> - step over single instruction. If instruction
+ is function call, execution continues until control returns from the function.
+
+ <li><code>RM_STEP_INTO = 2</code> - single instruction in given context.
+
+ <li><code>RM_STEP_OVER_LINE = 3</code> - resume execution of given context until control reaches instruction
+ that belongs to a different line of source code, but runs any functions called at
+ full speed. Error is returned if line number information not available.
+
+ <li><code>RM_STEP_INTO_LINE = 4</code> - resumes execution of given context until control reaches instruction
+ that belongs to a different line of source code. If a function is called,
+ stop at first line of the function code. Error is returned if line number
+ information not available.
+
+ <li><code>RM_STEP_OUT = 5</code> - resume execution of given context until control returns from current
+ function.
+</ul>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i>
+</font></b></pre>
+
+<h3><a name='CmdGetState'>Get State</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl getState <i>&lt;string: context ID&gt;</i>
+</font></b></pre>
+
+<p>The command retrieves current state of the context. The command should fail if HasState property of
+the context is false.</p>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i> <i>&lt;boolean: suspended&gt;</i>
+ <i>&lt;int: PC&gt;</i> <i>&lt;string: last state change reason&gt;</i> <i>&lt;state data&gt;</i>
+
+<i>&lt;state data&gt;</i>
+ <font face=Wingdings></font> null
+ <font face=Wingdings></font> <i>&lt;object: context state properties&gt;</i>
+</font></b></pre>
+
+<p>State change reason can be any text, but if it is one of predefined strings,
+a generic client might be able to handle it better. Predefined reasons are:</p>
+<ul>
+ <li><code>REASON_USER_REQUEST = "Suspended"</code> - context suspended by command.
+ <li><code>REASON_STEP = "Step"</code> - context resumed or suspended by step command.
+ <li><code>REASON_BREAKPOINT = "Breakpoint"</code> - context suspended by breakpoint.
+ <li><code>REASON_EXCEPTION = "Exception"</code> - context suspended by exception.
+ <li><code>REASON_CONTAINER = "Container"</code> - context suspended or resumed as part of container.
+ <li><code>REASON_WATCHPOINT = "Watchpoint"</code> - context suspended by watchpoint (data breakpoint).
+ <li><code>REASON_SIGNAL = "Signal"</code> - context suspended because it received a signal.
+ <li><code>REASON_SHAREDLIB = "Shared Library"</code> - context suspended because a shared library is loaded or unloaded.
+ <li><code>REASON_ERROR = "Error"</code> - context suspended because of an error in execution environment.
+</ul>
+
+<p>Context state properties can contain any data relevant to context state.
+Defenition of state properties depends on a target.</p>
+
+<h3><a name='CmdTerminate'>Terminate</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C <i>&lt;token&gt;</i> RunControl terminate <i>&lt;string: context ID&gt;</i>
+</font></b></pre>
+
+<p>The command terminates execution of given context. The command should fail if CanTerminate
+property of the context is false.</p>
+
+<p>Result message:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R <i>&lt;token&gt;</i> <i>&lt;error report&gt;</i>
+</font></b></pre>
+
+<h2><a name='Events'>Events</a></h2>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+E RunControl contextAdded <i>&lt;array of context data&gt;</i>
+
+E RunControl contextChanged <i>&lt;array of context data&gt;</i>
+
+E RunControl contextRemoved <i>&lt;array of context IDs&gt;</i>
+
+E RunControl contextSuspended <i>&lt;string: context ID&gt;</i> <i>&lt;int: PC&gt;</i>
+ <i>&lt;string: reason&gt;</i> <i>&lt;state data&gt;</i>
+
+E RunControl contextResumed <i>&lt;string: context ID&gt;</i>
+
+E RunControl contextException <i>&lt;string: context ID&gt;</i> <i>&lt;string: description&gt;</i>
+
+E RunControl containerSuspended <i>&lt;string: context ID&gt;</i> <i>&lt;int: PC&gt;</i>
+ <i>&lt;string: reason&gt;</i> <i>&lt;state data&gt;</i> <i>&lt;array of context IDs&gt;</i>
+
+E RunControl containerResumed <i>&lt;array of context IDs&gt;</i>
+
+<i>&lt;array of context data&gt;</i>
+ <font face=Wingdings></font> null
+ <font face=Wingdings></font> [ <i>&lt;context data list&gt;</i> ]
+
+<i>&lt;context data list&gt;</i>
+ <font face=Wingdings></font> <i>&lt;object: context data&gt;</i>
+ <font face=Wingdings></font> <i>&lt;context data list&gt;</i> , <i>&lt;object: context data&gt;</i>
+</font></b></pre>
+
+<dl>
+ <dt><b>contextAdded</b>
+ <dd>is sent when new contexts are created or attached for debugging. The message contains
+ array of context data. Context data is same as returned by Get Context command.
+ <dt><b>contextChanged</b>
+ <dd>is sent when context properties change. The message contains
+ array of changed (new) context data. Context data is same as returned by Get Context command.
+ <dt><b>contextRemoved</b>
+ <dd>is sent when context is removed - terminated or dettached. The message contains
+ array of context IDs.
+ <dt><b>contextSuspended</b>
+ <dd>is sent when context is suspended. The message context ID contains context state data,
+ same state data as returned by Get State command.
+ <dt><b>contextResumed</b>
+ <dd>is sent when context is resumed. The message contains resumed context ID.
+ <dt><b>contextException</b>
+ <dd>is sent when execution exception occurs in a context. The message contains context ID and
+ a string that describes nature of the exception.
+ <dt><b>containerSuspended</b>
+ <dd>is sent when target simultaneously suspends multiple threads in a container (process, core, etc.).
+ The message contains context ID and context state data of a context responsible for the event.
+ It can be container ID or any one of container children, for example, it can be thread
+ that hit "suspend all" breakpoint. Message also contains full list of all contexts that were suspended
+ simultaneously. No separate contextSuspened events are sent for contexts in the list. If client needs
+ state data for those contexts, it should use Get State command.
+ <dt><b>containerResumed</b>
+ <dd>is sent when target simultaneously resumes multiple threads in a container (process,
+ core, etc.). Message contains full list of all contexts that were resumed
+ simultaneously. No separate contextResumed events are sent for contexts in the list.
+</dl>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<font color=#7F0055>public interface</font> IRunControl <font color=#7F0055>extends</font> IService {
+
+ <font color=#3F5FBF>/**
+ * Context property names.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ PROP_ID = "ID",
+ PROP_PARENT_ID = "ParentID",
+ PROP_IS_CONTAINER = "IsContainer",
+ PROP_HAS_STATE = "HasState",
+ PROP_CAN_RESUME = "CanResume",
+ PROP_CAN_COUNT = "CanCount",
+ PROP_CAN_SUSPEND = "CanSuspend",
+ PROP_CAN_TERMINATE = "CanTerminate";
+
+ <font color=#3F5FBF>/**
+ * Context resume modes.
+ */</font>
+ <font color=#7F0055>static final int</font>
+ RM_RESUME = 0,
+ RM_STEP_OVER = 1,
+ RM_STEP_INTO = 2,
+ RM_STEP_OVER_LINE = 3,
+ RM_STEP_INTO_LINE = 4,
+ RM_STEP_OUT = 5;
+
+ <font color=#3F5FBF>/**
+ * State change reason of a context.
+ * Reason can be any text, but if it is one of predefined strings,
+ * a generic client might be able to handle it better.
+ */</font>
+ <font color=#7F0055>static final</font> String
+ REASON_USER_REQUEST = "Suspended",
+ REASON_STEP = "Step",
+ REASON_BREAKPOINT = "Breakpoint",
+ REASON_EXCEPTION = "Exception",
+ REASON_CONTAINER = "Container",
+ REASON_WATCHPOINT = "Watchpoint",
+ REASON_SIGNAL = "Signal",
+ REASON_SHAREDLIB = "Shared Library",
+ REASON_ERROR = "Error";
+
+ <font color=#3F5FBF>/**
+ * Retrieve context info for given context ID.
+ *
+ * <font color=#7F9FBF>@param</font> id context ID.
+ * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed.
+ */</font>
+ IToken getContext(String id, DoneGetContext done);
+
+ <font color=#3F5FBF>/**
+ * Client callback interface for getContext().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetContext {
+ <font color=#3F5FBF>/**
+ * Called when contexts data retrieval is done.
+ * <font color=#7F9FBF>@param</font> error error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> context context data.
+ */</font>
+ <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, RunControlContext context);
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve children of given context.
+ *
+ * <font color=#7F9FBF>@param</font> parent_context_id parent context ID. Can be null
+ * to retrieve top level of the hierarchy, or one of context IDs retrieved
+ * by previous getContext or getChildren commands.
+ * <font color=#7F9FBF>@param</font> done - callback interface called when operation is completed.
+ */</font>
+ IToken getChildren(String parent_context_id, DoneGetChildren done);
+
+ <font color=#3F5FBF>/**
+ * Client callback interface for getContexts().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetChildren {
+ <font color=#3F5FBF>/**
+ * Called when contexts data retrieval is done.
+ * <font color=#7F9FBF>@param</font> error error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> contexts array of available context IDs.
+ */</font>
+ <font color=#7F0055>void</font> doneGetChildren(IToken token, RunControlError error, Context[] contexts);
+ }
+
+ <font color=#3F5FBF>/**
+ * A context corresponds to an execution thread, process, address space, etc.
+ * A context can belong to a parent context. Contexts hierarchy can be simple
+ * plain list or it can form a tree. It is up to target agent developers to choose
+ * layout that is most descriptive for a given target. Context IDs are valid across
+ * all services. In other words, all services access same hierarchy of contexts,
+ * with same IDs, however, each service accesses its own subset of context's
+ * attributes and functionality, which is relevant to that service.
+ */</font>
+ <font color=#7F0055>interface</font> RunControlContext {
+
+ <font color=#3F5FBF>/**
+ * Retrieve context ID.
+ * Same as getProperties().get("ID")
+ */</font>
+ String getID();
+
+ <font color=#3F5FBF>/**
+ * Retrieve parent context ID.
+ * Same as getProperties().get("ParentID")
+ */</font>
+ String getParentID();
+
+ <font color=#3F5FBF>/**
+ * Get context properties. See PROP_* definitions for property names.
+ * Context properties are read only, clients should not try to modify them.
+ * <font color=#7F9FBF>@return</font> Map of context properties.
+ */</font>
+ Map&lt;String,Object&gt; getProperties();
+
+ <font color=#3F5FBF>/**
+ * Utility method to read context property PROP_IS_CONTAINER.
+ * Executing resume or suspend command on a container causes all its children to resume or suspend.
+ * <font color=#7F9FBF>@return</font> value of PROP_IS_CONTAINER.
+ */</font>
+ <font color=#7F0055>boolean</font> isContainer();
+
+ <font color=#3F5FBF>/**
+ * Utility method to read context property PROP_HAS_STATE.
+ * Only context that has a state can be resumed or suspended.
+ * <font color=#7F9FBF>@return</font> value of PROP_HAS_STATE.
+ */</font>
+ <font color=#7F0055>boolean</font> hasState();
+
+ <font color=#3F5FBF>/**
+ * Utility method to read context property PROP_CAN_SUSPEND.
+ * Value 'true' means suspend command is supported by the context,
+ * however the method does not check that the command can be executed successfully in
+ * the current state of the context. For example, the command still can fail if context is
+ * already suspended.
+ * <font color=#7F9FBF>@return</font> value of PROP_CAN_SUSPEND.
+ */</font>
+ <font color=#7F0055>boolean</font> canSuspend();
+
+ <font color=#3F5FBF>/**
+ * Utility method to read a 'mode' bit in context property PROP_CAN_RESUME.
+ * Value 'true' means resume command is supported by the context,
+ * however the method does not check that the command can be executed successfully in
+ * the current state of the context. For example, the command still can fail if context is
+ * already resumed.
+ * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*.
+ * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_RESUME.
+ */</font>
+ <font color=#7F0055>boolean</font> canResume(<font color=#7F0055>int</font> mode);
+
+ <font color=#3F5FBF>/**
+ * Utility method to read a 'mode' bit in context property PROP_CAN_COUNT.
+ * Value 'true' means resume command with count other then 1 is supported by the context,
+ * however the method does not check that the command can be executed successfully in
+ * the current state of the context. For example, the command still can fail if context is
+ * already resumed.
+ * <font color=#7F9FBF>@param</font> mode - resume mode, see RM_*.
+ * <font color=#7F9FBF>@return</font> value of requested bit of PROP_CAN_COUNT.
+ */</font>
+ <font color=#7F0055>boolean</font> canCount(<font color=#7F0055>int</font> mode);
+
+ <font color=#3F5FBF>/**
+ * Utility method to read context property PROP_CAN_TERMINATE.
+ * Value 'true' means terminate command is supported by the context,
+ * however the method does not check that the command can be executed successfully in
+ * the current state of the context. For example, the command still can fail if context is
+ * already exited.
+ * <font color=#7F9FBF>@return</font> value of PROP_CAN_SUSPEND.
+ */</font>
+ <font color=#7F0055>boolean</font> canTerminate();
+
+ <font color=#3F5FBF>/**
+ * Send a command to retrieve current state of a context.
+ * <font color=#7F9FBF>@param</font> done - command result call back object.
+ * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
+ */</font>
+ IToken getState(DoneGetState done);
+
+ <font color=#3F5FBF>/**
+ * Send a command to suspend a context.
+ * Also suspends children if context is a container.
+ * <font color=#7F9FBF>@param</font> done - command result call back object.
+ * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
+ */</font>
+ IToken suspend(DoneCommand done);
+
+ <font color=#3F5FBF>/**
+ * Send a command to resume a context.
+ * Also resumes children if context is a container.
+ * <font color=#7F9FBF>@param</font> mode - defines how to resume the context, see RM_*.
+ * <font color=#7F9FBF>@param</font> count - if mode implies stepping, defines how many steps to perform.
+ * <font color=#7F9FBF>@param</font> done - command result call back object.
+ * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
+ */</font>
+ IToken resume(<font color=#7F0055>int</font> mode, <font color=#7F0055>int</font> count, DoneCommand done);
+
+ <font color=#3F5FBF>/**
+ * Send a command to terminate a context.
+ * <font color=#7F9FBF>@param</font> done - command result call back object.
+ * <font color=#7F9FBF>@return</font> pending command handle, can be used to cancel the command.
+ */</font>
+ IToken terminate(DoneCommand done);
+ }
+
+ <font color=#7F0055>class</font> RunControlError <font color=#7F0055>extends</font> Exception {
+ }
+
+ <font color=#7F0055>interface</font> DoneGetState {
+ <font color=#7F0055>void</font> doneGetState(IToken token, Exception error, <font color=#7F0055>boolean</font> suspended, String pc,
+ String reason, Map&lt;String,Object&gt; params);
+ }
+
+ <font color=#7F0055>interface</font> DoneCommand {
+ <font color=#3F5FBF>/**
+ * Called when run control command execution is complete.
+ * <font color=#7F9FBF>@param</font> token - pending command handle.
+ * <font color=#7F9FBF>@param</font> error - command execution error or null.
+ */</font>
+ <font color=#7F0055>void</font> doneCommand(IToken token, Exception error);
+ }
+
+ <font color=#3F5FBF>/**
+ * Add run control event listener.
+ * <font color=#7F9FBF>@param</font> listener - run control event listener to add.
+ */</font>
+ <font color=#7F0055>void</font> addListener(RunControlListener listener);
+
+ <font color=#3F5FBF>/**
+ * Remove run control event listener.
+ * <font color=#7F9FBF>@param</font> listener - run control event listener to remove.
+ */</font>
+ <font color=#7F0055>void</font> removeListener(RunControlListener listener);
+
+ <font color=#3F5FBF>/**
+ * Service events listener interface.
+ */</font>
+ <font color=#7F0055>interface</font> RunControlListener {
+
+ <font color=#3F5FBF>/**
+ * Called when a new contexts are created.
+ * <font color=#7F9FBF>@param</font> contexts - array of new context properties.
+ */</font>
+ <font color=#7F0055>void</font> contextAdded(RunControlContext contexts[]);
+
+ <font color=#3F5FBF>/**
+ * Called when a context properties changed.
+ * <font color=#7F9FBF>@param</font> contexts - array of new context properties.
+ */</font>
+ <font color=#7F0055>void</font> contextChanged(RunControlContext contexts[]);
+
+ <font color=#3F5FBF>/**
+ * Called when contexts are removed.
+ * <font color=#7F9FBF>@param</font> context_ids - aray of removed context IDs.
+ */</font>
+ <font color=#7F0055>void</font> contextRemoved(String context_ids[]);
+
+ <font color=#3F5FBF>/**
+ * Called when a thread is suspended.
+ * <font color=#7F9FBF>@param</font> context - ID of a context that was suspended.
+ * <font color=#7F9FBF>@param</font> pc - program counter of the context, can be null.
+ * <font color=#7F9FBF>@param</font> reason - human readable description of suspend reason.
+ * <font color=#7F9FBF>@param</font> params - additional, target specific data about suspended context.
+ */</font>
+ <font color=#7F0055>void</font> contextSuspended(String context, String pc,
+ String reason, Map&lt;String,Object&gt; params);
+
+ <font color=#3F5FBF>/**
+ * Called when a thread is resumed.
+ * <font color=#7F9FBF>@param</font> context - ID of a context that was resumed.
+ */</font>
+ <font color=#7F0055>void</font> contextResumed(String context);
+
+ <font color=#3F5FBF>/**
+ * Called when target simultaneously suspends multiple threads in a container
+ * (process, core, etc.).
+ *
+ * <font color=#7F9FBF>@param</font> context - ID of a context responsible for the event. It can be container ID or
+ * any one of container children, for example, it can be thread that hit "suspend all" breakpoint.
+ * Client expected to move focus (selection) to this context.
+ * <font color=#7F9FBF>@param</font> pc - program counter of the context.
+ * <font color=#7F9FBF>@param</font> reason - human readable description of suspend reason.
+ * <font color=#7F9FBF>@param</font> params - additional target specific data about suspended context.
+ * <font color=#7F9FBF>@param</font> suspended_ids - full list of all contexts that were suspended.
+ */</font>
+ <font color=#7F0055>void</font> containerSuspended(String context, String pc,
+ String reason, Map&lt;String,Object&gt; params, String[] suspended_ids);
+
+ <font color=#3F5FBF>/**
+ * Called when target simultaneously resumes multiple threads in a container (process,
+ * core, etc.).
+ *
+ * <font color=#7F9FBF>@param</font> context_ids - full list of all contexts that were resumed.
+ */</font>
+ <font color=#7F0055>void</font> containerResumed(String[] context_ids);
+
+ <font color=#3F5FBF>/**
+ * Called when an exception is detected in a target thread.
+ * <font color=#7F9FBF>@param</font> context - ID of a context that caused an exception.
+ * <font color=#7F9FBF>@param</font> msg - human readable description of the exception.
+ */</font>
+ <font color=#7F0055>void</font> contextException(String context, String msg);
+ }
+}
+</pre>
+
+</body>
+</html>

Back to the top