--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/dsdp/tm/tcf_0_3_x/org.eclipse.tm.tcf.docs/TCF Service - Stack Trace.html Mon Aug 17 16:02:00 2009 -0500
@@ -0,0 +1,295 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+ <title>Target Communication Framework Services - Stack Trace</title>
+</head>
+
+<body lang='EN-US'>
+
+<h1>Target Communication Framework Services - Stack Trace</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>
+ </ul>
+ <li><a href='#Events'>Events</a>
+ <li><a href='#API'>API</a>
+</ul>
+
+<h1>Stack Trace 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
+</table>
+
+<h2><a name='Overview'>Overview</a></h2>
+
+<p>The service implements thread stack back tracing. 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>
+
+<h3><a name='CmdGetContext'>Get Context</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • <i><token></i> • StackTrace • getContext • <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>
+
+<p>The command retrieves context info for given context IDs.
+Command allows to query multiple contexts at once.
+Stack Trace context represents single stack frame.
+If target supports more then one stack per thread,
+each stack is also represented by a separate context.</p>
+
+<p>Reply:</p>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+R • <i><token></i> • <i><array of context data></i> • <i><error report></i> •
+
+<i><array of context data></i>
+ ⇒ null
+ ⇒ [ ]
+ ⇒ [ <i><context data list></i> ]
+
+<i><context data list></i>
+ ⇒ <i><context data></i>
+ ⇒ <i><context data list></i> , <i><context data></i>
+
+<i><context data></i>
+ ⇒ null
+ ⇒ <i><object></i>
+</font></b></pre>
+
+<p>Context data object should, at least, contain member
+<b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b>
+Context data is expected to be cached by clients.
+Cached context data should by flushed when parent thread is resumed.</p>
+
+<p>Predefined stack trace 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>
+ - process ID.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code>
+ - context name if context is a stack
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"FP" : <i><number></i></font></b></code>
+ - frame pointer - memory address of stack frame
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"PC" : <i><number></i></font></b></code>
+ - program counter - memory address of instruction that will be executed when thread returns from this stack frame.
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsCnt" : <i><number></i></font></b></code>
+ - function arguments count
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsAddr" : <i><number></i></font></b></code>
+ - memory address of function arguments
+
+ <li><code><b><font face="Courier New" size=2 color=#333399>"Level" : <i><number></i></font></b></code>
+ - frame level. Bottom most (oldest) frame is level 0.
+</ul>
+
+<h3><a name='CmdGetChildren'>Get Children</a></h3>
+
+<pre><b><font face="Courier New" size=2 color=#333399>
+C • <i><token></i> • StackTrace • getChildren • <i><string: parent context ID></i> •
+</font></b></pre>
+
+<p>The command retrieves stack trace context list.
+Parent context usually corresponds to an execution thread.
+Some targets have more then one stack. In such case children of a thread
+are stacks, and stack frames are deeper in the hierarchy - they can be
+retrieved with additional getChildren commands.</p>
+
+<p>The command will fail if parent thread is not suspended.
+Client can use Run Control service to suspend a thread.</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></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>
+
+
+<h2><a name='Events'>Events</a></h2>
+
+<p>No events are currently defined for Stack Trace service.</p>
+
+<h2><a name='API'>API</a></h2>
+
+<pre>
+<font color=#7F0055>public interface</font> IStackTrace <font color=#7F0055>extends</font> IService {
+
+ <font color=#7F0055>static final</font> String NAME = "StackTrace";
+
+ <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_NAME = "Name",
+ PROP_FRAME_ADDRESS = "FP",
+ PROP_PROGRAM_COUNTER = "PC",
+ PROP_ARGUMENTS_COUNT = "ArgsCnt",
+ PROP_ARGUMENTS_ADDRESS = "ArgsAddr",
+ PROP_LEVEL = "Level";
+
+ <font color=#3F5FBF>/**
+ * Retrieve context info for given context IDs.
+ *
+ * The command will fail if parent thread is not suspended.
+ * Client can use Run Control service to suspend a thread.
+ *
+ * <font color=#7F9FBF>@param</font> id – array of context IDs.
+ * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
+ */</font>
+ IToken getContext(String[] id, DoneGetContext done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for getContext().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetContext {
+ <font color=#3F5FBF>/**
+ * Called when context data retrieval is done.
+ * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> context – array of context data or null if error.
+ */</font>
+ <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, StackTraceContext[] context);
+ }
+
+ <font color=#3F5FBF>/**
+ * Retrieve stack trace context list.
+ * Parent context usually corresponds to an execution thread.
+ * Some targets have more then one stack. In such case children of a thread
+ * are stacks, and stack frames are deeper in the hierarchy - they can be
+ * retrieved with additional getChildren commands.
+ *
+ * The command will fail if parent thread is not suspended.
+ * Client can use Run Control service to suspend a thread.
+ *
+ * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID.
+ * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed.
+ */</font>
+ IToken getChildren(String parent_context_id, DoneGetChildren done);
+
+ <font color=#3F5FBF>/**
+ * Client call back interface for getChildren().
+ */</font>
+ <font color=#7F0055>interface</font> DoneGetChildren {
+ <font color=#3F5FBF>/**
+ * Called when context list retrieval is done.
+ * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded.
+ * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs.
+ * Stack frames are ordered from stack bottom to top.
+ */</font>
+ <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids);
+ }
+
+ <font color=#3F5FBF>/**
+ * StackTraceContext represents stack trace objects - stacks and stack frames.
+ */</font>
+ <font color=#7F0055>interface</font> StackTraceContext {
+
+ <font color=#3F5FBF>/**
+ * Get Context ID.
+ * <font color=#7F9FBF>@return</font> context ID.
+ */</font>
+ String getID();
+
+ <font color=#3F5FBF>/**
+ * Get parent context ID.
+ * <font color=#7F9FBF>@return</font> parent context ID.
+ */</font>
+ String getParentID();
+
+ <font color=#3F5FBF>/**
+ * Get context name - if context represents a stack.
+ * <font color=#7F9FBF>@return</font> context name or null.
+ */</font>
+ String getName();
+
+ <font color=#3F5FBF>/**
+ * Get memory address of this frame.
+ * <font color=#7F9FBF>@return</font> address or null if not a stack frame.
+ */</font>
+ Number getFrameAddress();
+
+ <font color=#3F5FBF>/**
+ * Get program counter saved in this stack frame -
+ * it is address of instruction to be executed when the function returns.
+ * <font color=#7F9FBF>@return</font> program counter or null if not a stack frame.
+ */</font>
+ Number getProgramCounter();
+
+ <font color=#3F5FBF>/**
+ * Get number of function arguments for this frame.
+ * <font color=#7F9FBF>@return</font> function arguments count.
+ */</font>
+ <font color=#7F0055>int</font> getArgumentsCount();
+
+ <font color=#3F5FBF>/**
+ * Get address of function arguments area in memory.
+ * <font color=#7F9FBF>@return</font> function arguments address or null if not available.
+ */</font>
+ Number getArgumentsAddress();
+
+ <font color=#3F5FBF>/**
+ * Get stack frame level.
+ * <font color=#7F9FBF>@return</font> frame level or 0 if not a stack frame.
+ */</font>
+ <font color=#7F0055>int</font> getLevel();
+
+ <font color=#3F5FBF>/**
+ * Get complete map of context properties.
+ * <font color=#7F9FBF>@return</font> map of context properties.
+ */</font>
+ Map<String,Object> getProperties();
+ }
+}
+</pre>
+
+</body>
+</html>