|
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
|
2 <html> |
|
3 <head> |
|
4 <title>Target Communication Framework Services - Stack Trace</title> |
|
5 </head> |
|
6 |
|
7 <body lang='EN-US'> |
|
8 |
|
9 <h1>Target Communication Framework Services - Stack Trace</h1> |
|
10 |
|
11 <ul> |
|
12 <li><a href='#VersionHistory'>Version History</a> |
|
13 <li><a href='#Overview'>Overview</a> |
|
14 <li><a href='#Cmds'>Commands</a> |
|
15 <ul> |
|
16 <li><a href='#CmdGetContext'>Get Context</a> |
|
17 <li><a href='#CmdGetChildren'>Get Children</a> |
|
18 </ul> |
|
19 <li><a href='#Events'>Events</a> |
|
20 <li><a href='#API'>API</a> |
|
21 </ul> |
|
22 |
|
23 <h1>Stack Trace Service</h1> |
|
24 |
|
25 <h2><a name='VersionHistory'>Version History</a></h2> |
|
26 |
|
27 <table border=1 cellpadding=8> |
|
28 <tr> |
|
29 <th>Version |
|
30 <th>Date |
|
31 <th>Change |
|
32 <tr> |
|
33 <td>0.1 |
|
34 <td>2008-01-10 |
|
35 <td>Initial contribution |
|
36 </table> |
|
37 |
|
38 <h2><a name='Overview'>Overview</a></h2> |
|
39 |
|
40 <p>The service implements thread stack back tracing. Command |
|
41 and event parameters are encoded as zero terminated <a href='TCF Specification.html#JSON'>JSON</a> strings.</p> |
|
42 |
|
43 <p>The service uses standard format for error reports, |
|
44 see <a href='TCF Services.html#ErrorFormat'>Error Report Format</a>.</p> |
|
45 |
|
46 <h2><a name='Cmds'>Commands</a></h2> |
|
47 |
|
48 <h3><a name='CmdGetContext'>Get Context</a></h3> |
|
49 |
|
50 <pre><b><font face="Courier New" size=2 color=#333399> |
|
51 C • <i><token></i> • StackTrace • getContext • <i><array of context IDs></i> • |
|
52 |
|
53 <i><array of context IDs></i> |
|
54 ⇒ null |
|
55 ⇒ [ ] |
|
56 ⇒ [ <i><context ID list></i> ] |
|
57 |
|
58 <i><context ID list></i> |
|
59 ⇒ <i><string: context ID></i> |
|
60 ⇒ <i><context ID list></i> , <i><string: context ID></i> |
|
61 </font></b></pre> |
|
62 |
|
63 <p>The command retrieves context info for given context IDs. |
|
64 Command allows to query multiple contexts at once. |
|
65 Stack Trace context represents single stack frame. |
|
66 If target supports more then one stack per thread, |
|
67 each stack is also represented by a separate context.</p> |
|
68 |
|
69 <p>Reply:</p> |
|
70 |
|
71 <pre><b><font face="Courier New" size=2 color=#333399> |
|
72 R • <i><token></i> • <i><array of context data></i> • <i><error report></i> • |
|
73 |
|
74 <i><array of context data></i> |
|
75 ⇒ null |
|
76 ⇒ [ ] |
|
77 ⇒ [ <i><context data list></i> ] |
|
78 |
|
79 <i><context data list></i> |
|
80 ⇒ <i><context data></i> |
|
81 ⇒ <i><context data list></i> , <i><context data></i> |
|
82 |
|
83 <i><context data></i> |
|
84 ⇒ null |
|
85 ⇒ <i><object></i> |
|
86 </font></b></pre> |
|
87 |
|
88 <p>Context data object should, at least, contain member |
|
89 <b><font face="Courier New" size=2 color=#333399>"ID" : <i><string>.</i></font></b> |
|
90 Context data is expected to be cached by clients. |
|
91 Cached context data should by flushed when parent thread is resumed.</p> |
|
92 |
|
93 <p>Predefined stack trace context properties are:</p> |
|
94 <ul> |
|
95 <li><code><b><font face="Courier New" size=2 color=#333399>"ID" : <i><string></i></font></b></code> |
|
96 - ID of the context, same as getContext command argument. |
|
97 |
|
98 <li><code><b><font face="Courier New" size=2 color=#333399>"ParentID" : <i><string></i></font></b></code> |
|
99 - ID of a parent context. |
|
100 |
|
101 <li><code><b><font face="Courier New" size=2 color=#333399>"ProcessID" : <i><string></i></font></b></code> |
|
102 - process ID. |
|
103 |
|
104 <li><code><b><font face="Courier New" size=2 color=#333399>"Name" : <i><string></i></font></b></code> |
|
105 - context name if context is a stack |
|
106 |
|
107 <li><code><b><font face="Courier New" size=2 color=#333399>"FP" : <i><number></i></font></b></code> |
|
108 - frame pointer - memory address of stack frame |
|
109 |
|
110 <li><code><b><font face="Courier New" size=2 color=#333399>"PC" : <i><number></i></font></b></code> |
|
111 - program counter - memory address of instruction that will be executed when thread returns from this stack frame. |
|
112 |
|
113 <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsCnt" : <i><number></i></font></b></code> |
|
114 - function arguments count |
|
115 |
|
116 <li><code><b><font face="Courier New" size=2 color=#333399>"ArgsAddr" : <i><number></i></font></b></code> |
|
117 - memory address of function arguments |
|
118 |
|
119 <li><code><b><font face="Courier New" size=2 color=#333399>"Level" : <i><number></i></font></b></code> |
|
120 - frame level. Bottom most (oldest) frame is level 0. |
|
121 </ul> |
|
122 |
|
123 <h3><a name='CmdGetChildren'>Get Children</a></h3> |
|
124 |
|
125 <pre><b><font face="Courier New" size=2 color=#333399> |
|
126 C • <i><token></i> • StackTrace • getChildren • <i><string: parent context ID></i> • |
|
127 </font></b></pre> |
|
128 |
|
129 <p>The command retrieves stack trace context list. |
|
130 Parent context usually corresponds to an execution thread. |
|
131 Some targets have more then one stack. In such case children of a thread |
|
132 are stacks, and stack frames are deeper in the hierarchy - they can be |
|
133 retrieved with additional getChildren commands.</p> |
|
134 |
|
135 <p>The command will fail if parent thread is not suspended. |
|
136 Client can use Run Control service to suspend a thread.</p> |
|
137 |
|
138 <p>Reply:</p> |
|
139 |
|
140 <pre><b><font face="Courier New" size=2 color=#333399> |
|
141 R • <i><token></i> • <i><error report></i> • <i><array of context IDs></i> •<i></i> |
|
142 |
|
143 <i><array of context IDs></i> |
|
144 ⇒ null |
|
145 ⇒ [ ] |
|
146 ⇒ [ <i><context ID list></i> ] |
|
147 |
|
148 <i><context ID list></i> |
|
149 ⇒ <i><string: context ID></i> |
|
150 ⇒ <i><context ID list></i> , <i><string: context ID></i> |
|
151 |
|
152 </font></b></pre> |
|
153 |
|
154 |
|
155 <h2><a name='Events'>Events</a></h2> |
|
156 |
|
157 <p>No events are currently defined for Stack Trace service.</p> |
|
158 |
|
159 <h2><a name='API'>API</a></h2> |
|
160 |
|
161 <pre> |
|
162 <font color=#7F0055>public interface</font> IStackTrace <font color=#7F0055>extends</font> IService { |
|
163 |
|
164 <font color=#7F0055>static final</font> String NAME = "StackTrace"; |
|
165 |
|
166 <font color=#3F5FBF>/** |
|
167 * Context property names. |
|
168 */</font> |
|
169 <font color=#7F0055>static final</font> String |
|
170 PROP_ID = "ID", |
|
171 PROP_PARENT_ID = "ParentID", |
|
172 PROP_PROCESS_ID = "ProcessID", |
|
173 PROP_NAME = "Name", |
|
174 PROP_FRAME_ADDRESS = "FP", |
|
175 PROP_PROGRAM_COUNTER = "PC", |
|
176 PROP_ARGUMENTS_COUNT = "ArgsCnt", |
|
177 PROP_ARGUMENTS_ADDRESS = "ArgsAddr", |
|
178 PROP_LEVEL = "Level"; |
|
179 |
|
180 <font color=#3F5FBF>/** |
|
181 * Retrieve context info for given context IDs. |
|
182 * |
|
183 * The command will fail if parent thread is not suspended. |
|
184 * Client can use Run Control service to suspend a thread. |
|
185 * |
|
186 * <font color=#7F9FBF>@param</font> id – array of context IDs. |
|
187 * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. |
|
188 */</font> |
|
189 IToken getContext(String[] id, DoneGetContext done); |
|
190 |
|
191 <font color=#3F5FBF>/** |
|
192 * Client call back interface for getContext(). |
|
193 */</font> |
|
194 <font color=#7F0055>interface</font> DoneGetContext { |
|
195 <font color=#3F5FBF>/** |
|
196 * Called when context data retrieval is done. |
|
197 * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. |
|
198 * <font color=#7F9FBF>@param</font> context – array of context data or null if error. |
|
199 */</font> |
|
200 <font color=#7F0055>void</font> doneGetContext(IToken token, Exception error, StackTraceContext[] context); |
|
201 } |
|
202 |
|
203 <font color=#3F5FBF>/** |
|
204 * Retrieve stack trace context list. |
|
205 * Parent context usually corresponds to an execution thread. |
|
206 * Some targets have more then one stack. In such case children of a thread |
|
207 * are stacks, and stack frames are deeper in the hierarchy - they can be |
|
208 * retrieved with additional getChildren commands. |
|
209 * |
|
210 * The command will fail if parent thread is not suspended. |
|
211 * Client can use Run Control service to suspend a thread. |
|
212 * |
|
213 * <font color=#7F9FBF>@param</font> parent_context_id – parent context ID. |
|
214 * <font color=#7F9FBF>@param</font> done - call back interface called when operation is completed. |
|
215 */</font> |
|
216 IToken getChildren(String parent_context_id, DoneGetChildren done); |
|
217 |
|
218 <font color=#3F5FBF>/** |
|
219 * Client call back interface for getChildren(). |
|
220 */</font> |
|
221 <font color=#7F0055>interface</font> DoneGetChildren { |
|
222 <font color=#3F5FBF>/** |
|
223 * Called when context list retrieval is done. |
|
224 * <font color=#7F9FBF>@param</font> error – error description if operation failed, null if succeeded. |
|
225 * <font color=#7F9FBF>@param</font> context_ids – array of available context IDs. |
|
226 * Stack frames are ordered from stack bottom to top. |
|
227 */</font> |
|
228 <font color=#7F0055>void</font> doneGetChildren(IToken token, Exception error, String[] context_ids); |
|
229 } |
|
230 |
|
231 <font color=#3F5FBF>/** |
|
232 * StackTraceContext represents stack trace objects - stacks and stack frames. |
|
233 */</font> |
|
234 <font color=#7F0055>interface</font> StackTraceContext { |
|
235 |
|
236 <font color=#3F5FBF>/** |
|
237 * Get Context ID. |
|
238 * <font color=#7F9FBF>@return</font> context ID. |
|
239 */</font> |
|
240 String getID(); |
|
241 |
|
242 <font color=#3F5FBF>/** |
|
243 * Get parent context ID. |
|
244 * <font color=#7F9FBF>@return</font> parent context ID. |
|
245 */</font> |
|
246 String getParentID(); |
|
247 |
|
248 <font color=#3F5FBF>/** |
|
249 * Get context name - if context represents a stack. |
|
250 * <font color=#7F9FBF>@return</font> context name or null. |
|
251 */</font> |
|
252 String getName(); |
|
253 |
|
254 <font color=#3F5FBF>/** |
|
255 * Get memory address of this frame. |
|
256 * <font color=#7F9FBF>@return</font> address or null if not a stack frame. |
|
257 */</font> |
|
258 Number getFrameAddress(); |
|
259 |
|
260 <font color=#3F5FBF>/** |
|
261 * Get program counter saved in this stack frame - |
|
262 * it is address of instruction to be executed when the function returns. |
|
263 * <font color=#7F9FBF>@return</font> program counter or null if not a stack frame. |
|
264 */</font> |
|
265 Number getProgramCounter(); |
|
266 |
|
267 <font color=#3F5FBF>/** |
|
268 * Get number of function arguments for this frame. |
|
269 * <font color=#7F9FBF>@return</font> function arguments count. |
|
270 */</font> |
|
271 <font color=#7F0055>int</font> getArgumentsCount(); |
|
272 |
|
273 <font color=#3F5FBF>/** |
|
274 * Get address of function arguments area in memory. |
|
275 * <font color=#7F9FBF>@return</font> function arguments address or null if not available. |
|
276 */</font> |
|
277 Number getArgumentsAddress(); |
|
278 |
|
279 <font color=#3F5FBF>/** |
|
280 * Get stack frame level. |
|
281 * <font color=#7F9FBF>@return</font> frame level or 0 if not a stack frame. |
|
282 */</font> |
|
283 <font color=#7F0055>int</font> getLevel(); |
|
284 |
|
285 <font color=#3F5FBF>/** |
|
286 * Get complete map of context properties. |
|
287 * <font color=#7F9FBF>@return</font> map of context properties. |
|
288 */</font> |
|
289 Map<String,Object> getProperties(); |
|
290 } |
|
291 } |
|
292 </pre> |
|
293 |
|
294 </body> |
|
295 </html> |