| <!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> |
| <li><a href='#CmdGetChildrenRange'>Get Children Range</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 |
| <tr> |
| <td>1.2 |
| <td>2013-07-12 |
| <td>New command: getChildrenRange. |
| Stack frame property "Level" is replaced with "Index". |
| <tr> |
| <td>1.3 |
| <td>2015-05-20 |
| <td>Fixed description of getChildrenRange. |
| New properties: CodeArea and FuncID. |
| </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>"TopFrame" : <i><boolean></i></font></b></code> |
| - true if the frame is top frame on a stack. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Index" : <i><number></i></font></b></code> |
| - frame index. Topmost (current) frame has index 0. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"Walk" : <i><boolean></i></font></b></code> |
| - true if the frame data was computed using symbols info, |
| false or not set if the data was collected using stack crawl logic. |
| |
| <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>"RP" : <i><number></i></font></b></code> |
| - return pointer - return address. |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"IP" : <i><number></i></font></b></code> |
| - instruction pointer - memory address of current instruction. |
| |
| <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>"CodeArea" : <i><number></i></font></b></code> |
| - source code location of the frame |
| |
| <li><code><b><font face="Courier New" size=2 color=#333399>"FuncID" : <i><number></i></font></b></code> |
| - function symbol ID. |
| </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 ID 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> |
| |
| <h3><a name='CmdGetChildrenRange'>Get Children Range</a></h3> |
| |
| <pre><b><font face="Courier New" size=2 color=#333399> |
| C • <i><token></i> • StackTrace • getChildrenRange • <i><string: parent context ID></i> • <i><int: range start></i> • <i><int: range end></i> • |
| </font></b></pre> |
| |
| <p>The command retrieves a range of stack trace context IDs. |
| Parent context usually corresponds to an execution thread.</p> |
| <p>Note: to allow partial and incremental stack tracing, IDs ordering in |
| the range is reversed relative to getChildren command order. |
| For example, range 0..1 represents last two stack frames: |
| current frame (top of the stack) and previous one.</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: same as Get Children reply.</p> |
| |
| <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", <font color=#3F5FBF>/** String, stack frame ID */</font> |
| PROP_PARENT_ID = "ParentID", <font color=#3F5FBF>/** String, stack frame parent ID */</font> |
| PROP_PROCESS_ID = "ProcessID", <font color=#3F5FBF>/** String, stack frame process ID */</font> |
| PROP_NAME = "Name", <font color=#3F5FBF>/** String, human readable name */</font> |
| PROP_TOP_FRAME = "TopFrame", <font color=#3F5FBF>/** Boolean, true if the frame is top frame on a stack */</font> |
| PROP_INDEX = "Index", <font color=#3F5FBF>/** Integer, stack frame index, starting from stack top (current frame) */</font> |
| PROP_WALK = "Walk", <font color=#3F5FBF>/** Boolean, true if the frame data was computed using symbols info */</font> |
| PROP_FRAME_ADDRESS = "FP", <font color=#3F5FBF>/** Number, stack frame memory address */</font> |
| PROP_RETURN_ADDRESS = "RP", <font color=#3F5FBF>/** Number, return address */</font> |
| PROP_INSTRUCTION_ADDRESS = "IP", <font color=#3F5FBF>/** Number, instruction pointer */</font> |
| PROP_ARGUMENTS_COUNT = "ArgsCnt", <font color=#3F5FBF>/** Integer, number of function arguments */</font> |
| PROP_ARGUMENTS_ADDRESS = "ArgsAddr", <font color=#3F5FBF>/** Number, memory address of function arguments */</font> |
| PROP_CODE_AREA = "CodeArea", <font color=#3F5FBF>/** ILineNumbers.CodeArea, source code location of the frame */</font> |
| PROP_FUNC_ID = "FuncID"; <font color=#3F5FBF>/** String, function symbol ID */</font> |
| |
| <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 ID 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. |
| * |
| * Stack frames are ordered from stack bottom to top. |
| * |
| * 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>/** |
| * Retrieve a range of stack trace context IDs. |
| * Parent context usually corresponds to an execution thread. |
| * |
| * Note: to allow partial and incremental stack tracing, IDs ordering in |
| * the range is reversed relative to getChildren command order. |
| * For example, range 0..1 represents last two stack frames: |
| * current frame (top of the stack) and previous one. |
| * |
| * 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> range_start - start of the range (inclusive). |
| * <font color=#7F9FBF>@param</font> range_end - end of the range (inclusive). |
| * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. |
| * <font color=#7F9FBF>@since 1.2</font> |
| */</font> |
| IToken getChildrenRange(String parent_context_id, int range_start, int range_end, DoneGetChildren done); |
| |
| <font color=#3F5FBF>/** |
| * Client call back interface for getChildren() and getChildrenRange(). |
| */</font> |
| <font color=#7F0055>interface</font> DoneGetChildren { |
| <font color=#3F5FBF>/** |
| * Called when context ID 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. |
| */</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> return address or null if not a stack frame. |
| */</font> |
| Number getReturnAddress(); |
| |
| <font color=#3F5FBF>/** |
| * Get address of the next instruction to be executed in this stack frame. |
| * For top frame it is same as PC register value. |
| * For other frames it is same as return address of the next frame. |
| * <font color=#7F9FBF>@return</font> instruction address or null if not a stack frame. |
| */</font> |
| Number getInstructionAddress(); |
| |
| <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 code area that describes source code location of the frame. |
| * If null, client should use LineNumbers service to find frame source location. |
| * <font color=#7F9FBF>@return</font> code area or null. |
| * <font color=#7F9FBF>@since 1.3</font> |
| */</font> |
| ILineNumbers.CodeArea getCodeArea(); |
| |
| <font color=#3F5FBF>/** |
| * Get function symbol ID. |
| * If null, client should use Symbols service to find function symbol ID. |
| * <font color=#7F9FBF>@return</font> function symbol ID or null. |
| * <font color=#7F9FBF>@since 1.3</font> |
| */</font> |
| String getFuncID(); |
| |
| <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> |