diff options
author | Eugene Tarassov | 2013-07-14 02:37:35 +0000 |
---|---|---|
committer | Eugene Tarassov | 2013-07-14 02:37:35 +0000 |
commit | 9742e5b1d384f4148b5f5c627b4a11f249bb912e (patch) | |
tree | 14a0b5444021fe0fe0cb65c1172d28bb9b19f69b | |
parent | d2f1bb2edabca3e5b4b9b2e602961fffc63766a5 (diff) | |
download | org.eclipse.tcf-9742e5b1d384f4148b5f5c627b4a11f249bb912e.tar.gz org.eclipse.tcf-9742e5b1d384f4148b5f5c627b4a11f249bb912e.tar.xz org.eclipse.tcf-9742e5b1d384f4148b5f5c627b4a11f249bb912e.zip |
Bug 411756 - [doc] Stacktrace service documentation should be updated with new properties and new command
4 files changed, 180 insertions, 26 deletions
diff --git a/docs/TCF Service - Stack Trace.html b/docs/TCF Service - Stack Trace.html index a9168d695..6801d90a2 100755 --- a/docs/TCF Service - Stack Trace.html +++ b/docs/TCF Service - Stack Trace.html @@ -15,7 +15,7 @@ <ul> <li><a href='#CmdGetContext'>Get Context</a> <li><a href='#CmdGetChildren'>Get Children</a> - </ul> + <li><a href='#CmdGetChildrenRange'>Get Children Range</a></ul> <li><a href='#Events'>Events</a> <li><a href='#API'>API</a> </ul> @@ -33,6 +33,11 @@ <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". </table> <h2><a name='Overview'>Overview</a></h2> @@ -107,8 +112,12 @@ Cached context data should by flushed when parent thread is resumed.</p> <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>"Level" : <i><number></i></font></b></code> - - frame level. Bottom most (oldest) frame is level 0. + <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. @@ -134,7 +143,7 @@ Cached context data should by flushed when parent thread is resumed.</p> C • <i><token></i> • StackTrace • getChildren • <i><string: parent context ID></i> • </font></b></pre> -<p>The command retrieves stack trace context list. +<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 @@ -159,6 +168,22 @@ R • <i><token></i> • <i><error report></i> • <i><a </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><int: range start></i> • <i><int: range end></i> • <i><string: parent context ID></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> @@ -180,7 +205,8 @@ R • <i><token></i> • <i><error report></i> • <i><a 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_LEVEL = "Level", <font color=#3F5FBF>/** Integer, stack frame level, starting from stack bottom */</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> @@ -211,12 +237,14 @@ R • <i><token></i> • <i><error report></i> • <i><a } <font color=#3F5FBF>/** - * Retrieve stack trace context list. + * 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. * @@ -226,14 +254,32 @@ R • <i><token></i> • <i><error report></i> • <i><a IToken getChildren(String parent_context_id, DoneGetChildren done); <font color=#3F5FBF>/** - * Client call back interface for getChildren(). + * 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> + 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 list retrieval is done. + * 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. - * Stack frames are ordered from stack bottom to top. */</font> <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); } diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/remote/StackTraceProxy.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/remote/StackTraceProxy.java index 4fc68b6f7..243ad4034 100644 --- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/remote/StackTraceProxy.java +++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/internal/services/remote/StackTraceProxy.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2007, 2011 Wind River Systems, Inc. and others. + * Copyright (c) 2007, 2013 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -91,6 +91,21 @@ public class StackTraceProxy implements IStackTrace { }.token; } + public IToken getChildrenRange(String parent_context_id, int range_start, int range_end, final DoneGetChildren done) { + return new Command(channel, this, "getChildrenRange", new Object[]{ parent_context_id, range_start, range_end }) { + @Override + public void done(Exception error, Object[] args) { + String[] arr = null; + if (error == null) { + assert args.length == 2; + error = toError(args[0]); + arr = toStringArray(args[1]); + } + done.doneGetChildren(token, error, arr); + } + }.token; + } + public IToken getContext(String[] id, final DoneGetContext done) { return new Command(channel, this, "getContext", new Object[]{ id }) { @Override diff --git a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/IStackTrace.java b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/IStackTrace.java index dfc9dd605..37fb284dc 100644 --- a/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/IStackTrace.java +++ b/plugins/org.eclipse.tcf.core/src/org/eclipse/tcf/services/IStackTrace.java @@ -1,5 +1,5 @@ /******************************************************************************* - * Copyright (c) 2007, 2011 Wind River Systems, Inc. and others. + * Copyright (c) 2007, 2013 Wind River Systems, Inc. and others. * All rights reserved. This program and the accompanying materials * are made available under the terms of the Eclipse Public License v1.0 * which accompanies this distribution, and is available at @@ -24,17 +24,48 @@ public interface IStackTrace extends IService { * Stack frame context property names. */ static final String - PROP_ID = "ID", /** String, stack frame ID */ - PROP_PARENT_ID = "ParentID", /** String, stack frame parent ID */ - PROP_PROCESS_ID = "ProcessID", /** String, stack frame process ID */ - PROP_NAME = "Name", /** String, human readable name */ - PROP_TOP_FRAME = "TopFrame", /** Boolean, true if the frame is top frame on a stack */ - PROP_LEVEL = "Level", /** Integer, stack frame level, starting from stack bottom */ - PROP_FRAME_ADDRESS = "FP", /** Number, stack frame memory address */ - PROP_RETURN_ADDRESS = "RP", /** Number, return address */ - PROP_INSTRUCTION_ADDRESS = "IP", /** Number, instruction pointer */ - PROP_ARGUMENTS_COUNT = "ArgsCnt", /** Integer, number of function arguments */ - PROP_ARGUMENTS_ADDRESS = "ArgsAddr"; /** Number, memory address of function arguments */ + /** String, stack frame ID */ + PROP_ID = "ID", + + /** String, stack frame parent ID */ + PROP_PARENT_ID = "ParentID", + + /** String, stack frame process ID */ + PROP_PROCESS_ID = "ProcessID", + + /** String, human readable name */ + PROP_NAME = "Name", + + /** Boolean, true if the frame is top frame on a stack */ + PROP_TOP_FRAME = "TopFrame", + + /** Integer, stack frame index, starting from stack top (current frame) */ + PROP_INDEX = "Index", + + /** Boolean, true if the frame data was computed using symbols info, + * false or not set if the data was collected using stack crawl logic. */ + PROP_WALK = "Walk", + + /** Number, stack frame memory address */ + PROP_FRAME_ADDRESS = "FP", + + /** Number, return address */ + PROP_RETURN_ADDRESS = "RP", + + /** Number, instruction pointer */ + PROP_INSTRUCTION_ADDRESS = "IP", + + /** Integer, number of function arguments */ + PROP_ARGUMENTS_COUNT = "ArgsCnt", + + /** Number, memory address of function arguments */ + PROP_ARGUMENTS_ADDRESS = "ArgsAddr"; + + static final String + /** Integer, stack frame level, starting from stack bottom + * @deprecated, use "Index" property. + * Note: "Index" is counted from the top of the stack, while "Level" is counted from the bottom. */ + PROP_LEVEL = "Level"; /** * Retrieve context info for given context IDs. @@ -60,12 +91,14 @@ public interface IStackTrace extends IService { } /** - * Retrieve stack trace context list. + * 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. * @@ -75,14 +108,32 @@ public interface IStackTrace extends IService { IToken getChildren(String parent_context_id, DoneGetChildren done); /** - * Client call back interface for getChildren(). + * 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. + * + * @param parent_context_id – parent context ID. + * @param range_start - start of the range (inclusive). + * @param range_end - end of the range (inclusive). + * @param done - call back interface called when operation is completed. + */ + IToken getChildrenRange(String parent_context_id, int range_start, int range_end, DoneGetChildren done); + + /** + * Client call back interface for getChildren() and getChildrenRange(). */ interface DoneGetChildren { /** - * Called when context list retrieval is done. + * Called when context ID list retrieval is done. * @param error – error description if operation failed, null if succeeded. * @param context_ids – array of available context IDs. - * Stack frames are ordered from stack bottom to top. */ void doneGetChildren(IToken token, Exception error, String[] context_ids); } diff --git a/plugins/org.eclipse.tcf.debug/src/org/eclipse/tcf/internal/debug/tests/TestExpressions.java b/plugins/org.eclipse.tcf.debug/src/org/eclipse/tcf/internal/debug/tests/TestExpressions.java index f9ebee153..39999aefa 100644 --- a/plugins/org.eclipse.tcf.debug/src/org/eclipse/tcf/internal/debug/tests/TestExpressions.java +++ b/plugins/org.eclipse.tcf.debug/src/org/eclipse/tcf/internal/debug/tests/TestExpressions.java @@ -67,6 +67,7 @@ class TestExpressions implements ITCFTest, private String suspended_pc; private boolean waiting_suspend; private String[] stack_trace; + private String[] stack_range; private IStackTrace.StackTraceContext[] stack_frames; private String[] local_var_expr_ids; private final Set<IToken> cmds = new HashSet<IToken>(); @@ -422,6 +423,47 @@ class TestExpressions implements ITCFTest, }); return; } + if (stack_range == null) { + srv_stk.getChildrenRange(thread_id, 1, 2, new IStackTrace.DoneGetChildren() { + public void doneGetChildren(IToken token, Exception error, String[] context_ids) { + if (error instanceof IErrorReport && ((IErrorReport)error).getErrorCode() == IErrorReport.TCF_ERROR_INV_COMMAND) { + /* Older agent, the command not available */ + stack_range = new String[0]; + runTest(); + } + else if (error != null) { + exit(error); + } + else if (context_ids == null) { + exit(new Exception("Invalid stack trace")); + } + else { + for (int i = 0; i < 2; i++) { + int j = stack_trace.length - i - 2; + if (i >= context_ids.length) { + if (j >= 0) { + exit(new Exception("Invalid result of doneGetChildren command: too short")); + } + } + else { + if (j < 0) { + exit(new Exception("Invalid result of doneGetChildren command: too long")); + } + if (context_ids[i]== null) { + exit(new Exception("Invalid result of doneGetChildren command: ID is null")); + } + if (!context_ids[i].equals(stack_trace[j])) { + exit(new Exception("Invalid result of doneGetChildren command: wrong ID")); + } + } + } + stack_range = context_ids; + runTest(); + } + } + }); + return; + } if (stack_frames == null) { srv_stk.getContext(stack_trace, new IStackTrace.DoneGetContext() { public void doneGetContext(IToken token, Exception error, IStackTrace.StackTraceContext[] frames) { |