| <!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='#VersionHistory'>Version History</a> |
| <li><a href='#Overview'>Overview</a> |
| <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> |
| <li><a href='#CmdDetach'>Detach</a> |
| </ul> |
| <li><a href='#Events'>Events</a> |
| <li><a href='#API'>API</a> |
| </ul> |
| |
| <h1>Run Control Service</h1> |
| |
| <h2><a name='VersionHistory'>Version History</a></h2> |
| |
| <table border=1 cellpadding=8> |
| <tr> |
| <th>Version |
| <th>Date |
| <th>Change |
| <tr> |
| <td>0.1 |
| <td>2008-01-10 |
| <td>Initial contribution |
| <tr> |
| <td>1.0 |
| <td>2008-05-06 |
| <td>Approved |
| <tr> |
| <td>1.1 |
| <td>2012-05-30 |
| <td>TCF release 1.0 |
| </table> |
| |
| <h2><a name='Overview'>Overview</a></h2> |
| |
| <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><token></i> • RunControl • getContext • <i><string: context ID></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><token></i> • <i><error report></i> • <i><context data></i> • |
| |
| <i><context data></i> |
| ⇒ null |
| ⇒ <i><object: context properties></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><string></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><string></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><string></i></font></b></code> |
| - ID of a parent context. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"ProcessID" : <i><string></i></font></b></code> |
| - ID of a process (memory space) of the context. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"CreatorID" : <i><string></i></font></b></code> |
| - ID of a context that created (started) this context. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> |
| - human redable context name. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"IsContainer" : <i><boolean></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><boolean></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><boolean></i></font></b></code> |
| - true if Suspend command is supported for this context. 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><int: bitset of resume modes></i></font></b></code> |
| - for each resume mode, corresponding bit is '1' if Resume command mode is supported for this context, 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><int: bitset of resume modes></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><boolean></i></font></b></code> |
| - true if Terminate command is supported by the context. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"CanDetach" : <i><boolean></i></font></b></code> |
| - true if Detach command is supported by the context. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"RCGroup" : <i><string></i></font></b></code> |
| - context ID of a run control group that contains the context. |
| Members of same group are always suspended and resumed together: |
| resuming/suspending a context resumes/suspends all members of the group |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"BPGroup" : <i><string></i></font></b></code> |
| - context ID of a breakpoints group that contains the context. |
| Members of same group share same breakpoint instances: |
| a breakpoint is planted once for the group, no need to plant |
| the breakpoint for each member of the group |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SymbolsGroup" : <i><string></i></font></b></code> |
| - Context ID of a symbols group that contains the context. |
| Members of a symbols group share same symbol reader configuration settings, |
| like user defined memory map entries and source lookup info |
| </ul> |
| |
| <h3><a name='CmdGetChildren'>Get Children</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • getChildren • <i><string: parent context ID></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><token></i> • <i><error report></i> • <i><array of context IDs></i> • |
| |
| <i><array of context IDs></i> |
| ⇒ null |
| ⇒ [ <i><context ID list></i> ] |
| |
| <i><context ID list></i> |
| ⇒ <i><string: context ID></i> |
| ⇒ <i><context ID list></i> , <i><string: context ID></i> |
| </font></b></pre> |
| |
| <h3><a name='CmdSuspend'>Suspend</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • suspend • <i><string: context ID></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><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdResume'>Resume</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • resume • <i><string: context ID></i> • <i><int: mode></i> • <i><int: count></i> • |
| C • <i><token></i> • RunControl • resume • <i><string: context ID></i> • <i><int: mode></i> • <i><int: count></i> • <i><object: parameters></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>The command can have optional argument that contains set of resume parameters, for example stepping range definition.</p> |
| |
| <p>Resume modes:</p> |
| <ul> |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>0</b></font></code> |
| - resume normal execution. Execution will |
| continue until suspended by command or breakpoint. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>1</b></font></code> |
| - step over a single instruction. If instruction |
| is function call, execution continues until control returns from the function. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>2</b></font></code> |
| - single instruction in given context. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>3</b></font></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> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>4</b></font></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> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>5</b></font></code> |
| - resume execution of given context until control returns from current |
| function. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>6</b></font></code> |
| - resume backward execution. Execution will |
| continue until suspended by command or breakpoint. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>7</b></font></code> |
| - reverse step over a single instruction. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>8</b></font></code> |
| - reverse step into a single instruction in the given context. |
| This effectively "un-executes" the previous instruction. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>9</b></font></code> |
| - resume backward execution |
| of the context until control reaches an instruction that belongs to a different source line. |
| If the line contains a function call then don't stop until get out of the function. |
| Error is returned if line number information not available. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>10</b></font></code> |
| - resume backward execution of the context |
| until control reaches an instruction that belongs to a different line of source code. |
| If a function is called, stop at the beginning of the last line of the function code. |
| Error is returned if line number information not available. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>11</b></font></code> |
| - resume backward execution of |
| the context until control reaches the point where the current function was called. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>12</b></font></code> |
| - step over instructions until PC is outside the specified range. |
| A function call within the range is considered to be in range. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>13</b></font></code> |
| - step instruction until PC is outside the specified range for any reason. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>14</b></font></code> |
| - resume backward execution until PC is outside the specified range. |
| A function call within the range is considered to be in range. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>15</b></font></code> |
| - resume backward execution until PC is outside the specified range for any reason. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>16</b></font></code> |
| - run until the context becomes active - scheduled to run on a target CPU. |
| </li> |
| |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>17</b></font></code> |
| - run reverse until the context becomes active. |
| </li> |
| </ul> |
| |
| <p>Resume parameters names:</p> |
| <ul> |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>"RangeStart" : <i><number></i></b></font></code> |
| starting address of step range, inclusive. |
| </li> |
| <li> |
| <code><b><font face="Courier New" size=2 color=#333399>"RangeEnd" : <i><number></i></b></font></code> |
| ending address of step range, exclusive. |
| </li> |
| </ul> |
| |
| <p>Result message:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdGetState'>Get State</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • getState • <i><string: context ID></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><token></i> • <i><error report></i> • <i><boolean: suspended></i> • |
| <i><int: PC></i> • <i><string: last state change reason></i> • <i><state data></i> • |
| |
| <i><state data></i> |
| ⇒ null |
| ⇒ <i><object: context state properties></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><b><font face="Courier New" size=2 color=#333399>"Suspended"</b></font></code> |
| - context suspended by command. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Step"</b></font></code> |
| - context suspended by step command. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Breakpoint"</b></font></code> |
| - context suspended by breakpoint. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Exception"</b></font></code> |
| - context suspended by exception. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Container"</b></font></code> |
| - context suspended as part of container. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Watchpoint"</b></font></code> |
| - context suspended by watchpoint (data breakpoint). |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Signal"</b></font></code> |
| - context suspended because it received a signal. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Shared Library"</b></font></code> |
| - context suspended because a shared library is loaded or unloaded. |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Error"</b></font></code> |
| - context suspended because of an error in execution environment. |
| </ul> |
| |
| <p>Context state properties can contain any data relevant to context state. |
| Definition of state properties depends on a target. Predefined properties are:</p> |
| <ul> |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Signal" : <i><int></i></b></font></code> |
| - signal that caused the context to become suspended |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SignalName" : <i><string></i></b></font></code> |
| - name of the signal that caused the context to become suspended |
| <li><code><b><font face="Courier New" size=2 color=#333399>"SignalDescription" : <i><string></i></b></font></code> |
| - description of the signal that caused the context to become suspended |
| <li><code><b><font face="Courier New" size=2 color=#333399>"BPs" : <i><array of string></i></b></font></code> |
| - IDs of breakpoints that were triggered by the context |
| <li><code><b><font face="Courier New" size=2 color=#333399>"PCError" : <i><object></i></b></font></code> |
| - error report that describes a reason why program counter of the context is not available |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Reversing" : <i><boolean></i></b></font></code> |
| - true if the context is running in reverse |
| </ul> |
| |
| <h3><a name='CmdTerminate'>Terminate</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • terminate • <i><string: context ID></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><token></i> • <i><error report></i> • |
| </font></b></pre> |
| |
| <h3><a name='CmdDetach'>Detach</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • RunControl • detach • <i><string: context ID></i> • |
| </font></b></pre> |
| |
| <p>The command detaches debugger from the context. The command should fail if CanDetach |
| property of the context is false.</p> |
| |
| <p>Result message:</p> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| R • <i><token></i> • <i><error report></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><array of context data></i> • |
| |
| E • RunControl • contextChanged • <i><array of context data></i> • |
| |
| E • RunControl • contextRemoved • <i><array of context IDs></i> • |
| |
| E • RunControl • contextSuspended • <i><string: context ID></i> • <i><int: PC></i> • |
| <i><string: reason></i> • <i><state data></i> • |
| |
| E • RunControl • contextResumed • <i><string: context ID></i> • |
| |
| E • RunControl • contextException • <i><string: context ID></i> • <i><string: description></i> • |
| |
| E • RunControl • containerSuspended • <i><string: context ID></i> • <i><int: PC></i> • |
| <i><string: reason></i> • <i><state data></i> • <i><array of context IDs></i> • |
| |
| E • RunControl • containerResumed • <i><array of context IDs></i> • |
| |
| <i><array of context data></i> |
| ⇒ null |
| ⇒ [ <i><context data list></i> ] |
| |
| <i><context data list></i> |
| ⇒ <i><object: context data></i> |
| ⇒ <i><context data list></i> , <i><object: context data></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 detached. 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_PROCESS_ID = "ProcessID", |
| PROP_CREATOR_ID = "CreatorID", |
| PROP_NAME = "Name", |
| PROP_IS_CONTAINER = "IsContainer", |
| PROP_HAS_STATE = "HasState", |
| PROP_CAN_RESUME = "CanResume", |
| PROP_CAN_COUNT = "CanCount", |
| PROP_CAN_SUSPEND = "CanSuspend", |
| PROP_CAN_TERMINATE = "CanTerminate", |
| PROP_CAN_DETACH = "CanDetach", |
| PROP_RC_GROUP = "RCGroup", |
| PROP_BP_GROUP = "BPGroup", |
| PROP_SYMBOLS_GROUP = "SymbolsGroup"; |
| |
| <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, |
| RM_REVERSE_RESUME = 6, |
| RM_REVERSE_STEP_OVER = 7, |
| RM_REVERSE_STEP_INTO = 8, |
| RM_REVERSE_STEP_OVER_LINE = 9, |
| RM_REVERSE_STEP_INTO_LINE = 10, |
| RM_REVERSE_STEP_OUT = 11, |
| RM_STEP_OVER_RANGE = 12, |
| RM_STEP_INTO_RANGE = 13, |
| RM_REVERSE_STEP_OVER_RANGE = 14, |
| RM_REVERSE_STEP_INTO_RANGE = 15, |
| RM_UNTIL_ACTIVE = 16, |
| RM_REVERSE_UNTIL_ACTIVE = 17; |
| |
| <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>/** |
| * Optional parameters of context state. |
| */</font> |
| <font color=#7F0055>static final</font> String |
| STATE_SIGNAL = "Signal", |
| STATE_SIGNAL_NAME = "SignalName", |
| STATE_SIGNAL_DESCRIPTION = "SignalDescription", |
| STATE_BREAKPOINT_IDS = "BPs", |
| STATE_PC_ERROR = "PCError", |
| STATE_REVERSING = "Reversing"; |
| |
| <font color=#3F5FBF>/** |
| * Optional parameters of resume command. |
| */</font> |
| <font color=#7F0055>static final</font> String |
| RP_RANGE_START = "RangeStart", |
| RP_RANGE_END = "RangeEnd"; |
| |
| <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>/** |
| * 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<String,Object> getProperties(); |
| |
| <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>/** |
| * Retrieve context process ID. |
| * Same as getProperties().get("ProcessID") |
| */</font> |
| String getProcessID(); |
| |
| <font color=#3F5FBF>/** |
| * Retrieve context creator ID. |
| * Same as getProperties().get("CreatorID") |
| */</font> |
| String getCreatorID(); |
| |
| <font color=#3F5FBF>/** |
| * Retrieve human readable context name. |
| * Same as getProperties().get("Name") |
| */</font> |
| String getName(); |
| |
| <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_TERMINATE. |
| */</font> |
| <font color=#7F0055>boolean</font> canTerminate(); |
| |
| <font color=#3F5FBF>/** |
| * Utility method to read context property PROP_CAN_DETACH. |
| * Value 'true' means detach 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 the context |
| * already has exited. |
| * <font color=#7F9FBF>@return</font> value of PROP_CAN_DETACH. |
| */</font> |
| <font color=#7F0055>boolean</font> canDetach(); |
| |
| <font color=#3F5FBF>/** |
| * Utility method to read context property PROP_RC_GROUP - |
| * context ID of a run control group that contains the context. |
| * Members of same group are always suspended and resumed together: |
| * resuming/suspending a context resumes/suspends all members of the group. |
| * <font color=#7F9FBF>@return</font> value of PROP_RC_GROUP. |
| */</font> |
| String getRCGroup(); |
| |
| <font color=#3F5FBF>/** |
| * Utility method to read context property PROP_BP_GROUP - |
| * context ID of a breakpoints group that contains the context. |
| * Members of same group share same breakpoint instances: |
| * a breakpoint is planted once for the group, no need to plant |
| * the breakpoint for each member of the group |
| * <font color=#7F9FBF>@return</font> value of PROP_BP_GROUP or null if the context does not support breakpoints. |
| */</font> |
| String getBPGroup(); |
| |
| <font color=#3F5FBF>/** |
| * Utility method to read context property PROP_SYMBOLS_GROUP - |
| * context ID of a symbols group that contains the context. |
| * Members of a symbols group share same symbol reader configuration settings, |
| * like user defined memory map entries and source lookup info. |
| * <font color=#7F9FBF>@return</font> value of PROP_SYMBOLS_GROUP or null if the context is not a member of a symbols group. |
| */</font> |
| String getSymbolsGroup(); |
| |
| <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, PROP_CAN_DETACH 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=#3F5FBF>/** |
| * Send a command to detach 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 detach(DoneCommand done); |
| } |
| |
| <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<String,Object> 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 - array 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<String,Object> 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<String,Object> 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> |