Commit | Line | Data |
---|---|---|
02d27625 MM |
1 | /* Branch trace support for GDB, the GNU debugger. |
2 | ||
32d0add0 | 3 | Copyright (C) 2013-2015 Free Software Foundation, Inc. |
02d27625 MM |
4 | |
5 | Contributed by Intel Corp. <markus.t.metzger@intel.com>. | |
6 | ||
7 | This file is part of GDB. | |
8 | ||
9 | This program is free software; you can redistribute it and/or modify | |
10 | it under the terms of the GNU General Public License as published by | |
11 | the Free Software Foundation; either version 3 of the License, or | |
12 | (at your option) any later version. | |
13 | ||
14 | This program is distributed in the hope that it will be useful, | |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | GNU General Public License for more details. | |
18 | ||
19 | You should have received a copy of the GNU General Public License | |
20 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ | |
21 | ||
22 | #ifndef BTRACE_H | |
23 | #define BTRACE_H | |
24 | ||
25 | /* Branch tracing (btrace) is a per-thread control-flow execution trace of the | |
26 | inferior. For presentation purposes, the branch trace is represented as a | |
27 | list of sequential control-flow blocks, one such list per thread. */ | |
28 | ||
29 | #include "btrace-common.h" | |
9e8915c6 | 30 | #include "target/waitstatus.h" /* For enum target_stop_reason. */ |
02d27625 | 31 | |
b20a6524 MM |
32 | #if defined (HAVE_LIBIPT) |
33 | # include <intel-pt.h> | |
34 | #endif | |
35 | ||
02d27625 | 36 | struct thread_info; |
23a7fe75 | 37 | struct btrace_function; |
02d27625 | 38 | |
7d5c24b3 MM |
39 | /* A coarse instruction classification. */ |
40 | enum btrace_insn_class | |
41 | { | |
42 | /* The instruction is something not listed below. */ | |
43 | BTRACE_INSN_OTHER, | |
44 | ||
45 | /* The instruction is a function call. */ | |
46 | BTRACE_INSN_CALL, | |
47 | ||
48 | /* The instruction is a function return. */ | |
49 | BTRACE_INSN_RETURN, | |
50 | ||
51 | /* The instruction is an unconditional jump. */ | |
52 | BTRACE_INSN_JUMP | |
53 | }; | |
54 | ||
da8c46d2 MM |
55 | /* Instruction flags. */ |
56 | enum btrace_insn_flag | |
57 | { | |
58 | /* The instruction has been executed speculatively. */ | |
59 | BTRACE_INSN_FLAG_SPECULATIVE = (1 << 0) | |
60 | }; | |
61 | ||
02d27625 MM |
62 | /* A branch trace instruction. |
63 | ||
64 | This represents a single instruction in a branch trace. */ | |
23a7fe75 | 65 | struct btrace_insn |
02d27625 MM |
66 | { |
67 | /* The address of this instruction. */ | |
68 | CORE_ADDR pc; | |
7d5c24b3 MM |
69 | |
70 | /* The size of this instruction in bytes. */ | |
71 | gdb_byte size; | |
72 | ||
73 | /* The instruction class of this instruction. */ | |
74 | enum btrace_insn_class iclass; | |
da8c46d2 MM |
75 | |
76 | /* A bit vector of BTRACE_INSN_FLAGS. */ | |
77 | enum btrace_insn_flag flags; | |
02d27625 MM |
78 | }; |
79 | ||
23a7fe75 MM |
80 | /* A vector of branch trace instructions. */ |
81 | typedef struct btrace_insn btrace_insn_s; | |
82 | DEF_VEC_O (btrace_insn_s); | |
83 | ||
84 | /* A doubly-linked list of branch trace function segments. */ | |
85 | struct btrace_func_link | |
86 | { | |
87 | struct btrace_function *prev; | |
88 | struct btrace_function *next; | |
89 | }; | |
90 | ||
91 | /* Flags for btrace function segments. */ | |
92 | enum btrace_function_flag | |
93 | { | |
94 | /* The 'up' link interpretation. | |
95 | If set, it points to the function segment we returned to. | |
96 | If clear, it points to the function segment we called from. */ | |
97 | BFUN_UP_LINKS_TO_RET = (1 << 0), | |
98 | ||
99 | /* The 'up' link points to a tail call. This obviously only makes sense | |
100 | if bfun_up_links_to_ret is clear. */ | |
101 | BFUN_UP_LINKS_TO_TAILCALL = (1 << 1) | |
102 | }; | |
103 | ||
31fd9caa MM |
104 | /* Decode errors for the BTS recording format. */ |
105 | enum btrace_bts_error | |
106 | { | |
107 | /* The instruction trace overflowed the end of the trace block. */ | |
108 | BDE_BTS_OVERFLOW = 1, | |
109 | ||
110 | /* The instruction size could not be determined. */ | |
111 | BDE_BTS_INSN_SIZE | |
112 | }; | |
113 | ||
b20a6524 MM |
114 | /* Decode errors for the Intel(R) Processor Trace recording format. */ |
115 | enum btrace_pt_error | |
116 | { | |
117 | /* The user cancelled trace processing. */ | |
118 | BDE_PT_USER_QUIT = 1, | |
119 | ||
120 | /* Tracing was temporarily disabled. */ | |
121 | BDE_PT_DISABLED, | |
122 | ||
123 | /* Trace recording overflowed. */ | |
124 | BDE_PT_OVERFLOW | |
125 | ||
126 | /* Negative numbers are used by the decoder library. */ | |
127 | }; | |
128 | ||
23a7fe75 | 129 | /* A branch trace function segment. |
02d27625 MM |
130 | |
131 | This represents a function segment in a branch trace, i.e. a consecutive | |
23a7fe75 MM |
132 | number of instructions belonging to the same function. |
133 | ||
31fd9caa MM |
134 | In case of decode errors, we add an empty function segment to indicate |
135 | the gap in the trace. | |
136 | ||
137 | We do not allow function segments without instructions otherwise. */ | |
23a7fe75 | 138 | struct btrace_function |
02d27625 | 139 | { |
23a7fe75 | 140 | /* The full and minimal symbol for the function. Both may be NULL. */ |
02d27625 MM |
141 | struct minimal_symbol *msym; |
142 | struct symbol *sym; | |
143 | ||
23a7fe75 MM |
144 | /* The previous and next segment belonging to the same function. |
145 | If a function calls another function, the former will have at least | |
146 | two segments: one before the call and another after the return. */ | |
147 | struct btrace_func_link segment; | |
148 | ||
149 | /* The previous and next function in control flow order. */ | |
150 | struct btrace_func_link flow; | |
151 | ||
152 | /* The directly preceding function segment in a (fake) call stack. */ | |
153 | struct btrace_function *up; | |
154 | ||
155 | /* The instructions in this function segment. | |
31fd9caa MM |
156 | The instruction vector will be empty if the function segment |
157 | represents a decode error. */ | |
23a7fe75 MM |
158 | VEC (btrace_insn_s) *insn; |
159 | ||
31fd9caa MM |
160 | /* The error code of a decode error that led to a gap. |
161 | Must be zero unless INSN is empty; non-zero otherwise. */ | |
162 | int errcode; | |
163 | ||
23a7fe75 | 164 | /* The instruction number offset for the first instruction in this |
31fd9caa MM |
165 | function segment. |
166 | If INSN is empty this is the insn_offset of the succeding function | |
167 | segment in control-flow order. */ | |
23a7fe75 MM |
168 | unsigned int insn_offset; |
169 | ||
31fd9caa MM |
170 | /* The function number in control-flow order. |
171 | If INSN is empty indicating a gap in the trace due to a decode error, | |
172 | we still count the gap as a function. */ | |
23a7fe75 MM |
173 | unsigned int number; |
174 | ||
175 | /* The function level in a back trace across the entire branch trace. | |
176 | A caller's level is one lower than the level of its callee. | |
177 | ||
178 | Levels can be negative if we see returns for which we have not seen | |
179 | the corresponding calls. The branch trace thread information provides | |
180 | a fixup to normalize function levels so the smallest level is zero. */ | |
181 | int level; | |
182 | ||
23a7fe75 MM |
183 | /* A bit-vector of btrace_function_flag. */ |
184 | enum btrace_function_flag flags; | |
02d27625 MM |
185 | }; |
186 | ||
23a7fe75 MM |
187 | /* A branch trace instruction iterator. */ |
188 | struct btrace_insn_iterator | |
189 | { | |
190 | /* The branch trace function segment containing the instruction. | |
191 | Will never be NULL. */ | |
192 | const struct btrace_function *function; | |
02d27625 | 193 | |
23a7fe75 MM |
194 | /* The index into the function segment's instruction vector. */ |
195 | unsigned int index; | |
196 | }; | |
02d27625 | 197 | |
23a7fe75 MM |
198 | /* A branch trace function call iterator. */ |
199 | struct btrace_call_iterator | |
200 | { | |
201 | /* The branch trace information for this thread. Will never be NULL. */ | |
202 | const struct btrace_thread_info *btinfo; | |
203 | ||
204 | /* The branch trace function segment. | |
205 | This will be NULL for the iterator pointing to the end of the trace. */ | |
206 | const struct btrace_function *function; | |
207 | }; | |
02d27625 MM |
208 | |
209 | /* Branch trace iteration state for "record instruction-history". */ | |
23a7fe75 | 210 | struct btrace_insn_history |
02d27625 | 211 | { |
23a7fe75 MM |
212 | /* The branch trace instruction range from BEGIN (inclusive) to |
213 | END (exclusive) that has been covered last time. */ | |
214 | struct btrace_insn_iterator begin; | |
215 | struct btrace_insn_iterator end; | |
02d27625 MM |
216 | }; |
217 | ||
218 | /* Branch trace iteration state for "record function-call-history". */ | |
23a7fe75 | 219 | struct btrace_call_history |
02d27625 | 220 | { |
23a7fe75 MM |
221 | /* The branch trace function range from BEGIN (inclusive) to END (exclusive) |
222 | that has been covered last time. */ | |
223 | struct btrace_call_iterator begin; | |
224 | struct btrace_call_iterator end; | |
02d27625 MM |
225 | }; |
226 | ||
52834460 MM |
227 | /* Branch trace thread flags. */ |
228 | enum btrace_thread_flag | |
229 | { | |
230 | /* The thread is to be stepped forwards. */ | |
231 | BTHR_STEP = (1 << 0), | |
232 | ||
233 | /* The thread is to be stepped backwards. */ | |
234 | BTHR_RSTEP = (1 << 1), | |
235 | ||
236 | /* The thread is to be continued forwards. */ | |
237 | BTHR_CONT = (1 << 2), | |
238 | ||
239 | /* The thread is to be continued backwards. */ | |
240 | BTHR_RCONT = (1 << 3), | |
241 | ||
242 | /* The thread is to be moved. */ | |
243 | BTHR_MOVE = (BTHR_STEP | BTHR_RSTEP | BTHR_CONT | BTHR_RCONT) | |
244 | }; | |
245 | ||
b0627500 MM |
246 | #if defined (HAVE_LIBIPT) |
247 | /* A packet. */ | |
248 | struct btrace_pt_packet | |
249 | { | |
250 | /* The offset in the trace stream. */ | |
251 | uint64_t offset; | |
252 | ||
253 | /* The decode error code. */ | |
254 | enum pt_error_code errcode; | |
255 | ||
256 | /* The decoded packet. Only valid if ERRCODE == pte_ok. */ | |
257 | struct pt_packet packet; | |
258 | }; | |
259 | ||
260 | /* Define functions operating on a vector of packets. */ | |
261 | typedef struct btrace_pt_packet btrace_pt_packet_s; | |
262 | DEF_VEC_O (btrace_pt_packet_s); | |
263 | #endif /* defined (HAVE_LIBIPT) */ | |
264 | ||
265 | /* Branch trace iteration state for "maintenance btrace packet-history". */ | |
266 | struct btrace_maint_packet_history | |
267 | { | |
268 | /* The branch trace packet range from BEGIN (inclusive) to | |
269 | END (exclusive) that has been covered last time. */ | |
270 | unsigned int begin; | |
271 | unsigned int end; | |
272 | }; | |
273 | ||
274 | /* Branch trace maintenance information per thread. | |
275 | ||
276 | This information is used by "maintenance btrace" commands. */ | |
277 | struct btrace_maint_info | |
278 | { | |
279 | /* Most information is format-specific. | |
280 | The format can be found in the BTRACE.DATA.FORMAT field of each thread. */ | |
281 | union | |
282 | { | |
283 | /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_BTS */ | |
284 | struct | |
285 | { | |
286 | /* The packet history iterator. | |
287 | We are iterating over BTRACE.DATA.FORMAT.VARIANT.BTS.BLOCKS. */ | |
288 | struct btrace_maint_packet_history packet_history; | |
289 | } bts; | |
290 | ||
291 | #if defined (HAVE_LIBIPT) | |
292 | /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_PT */ | |
293 | struct | |
294 | { | |
295 | /* A vector of decoded packets. */ | |
296 | VEC (btrace_pt_packet_s) *packets; | |
297 | ||
298 | /* The packet history iterator. | |
299 | We are iterating over the above PACKETS vector. */ | |
300 | struct btrace_maint_packet_history packet_history; | |
301 | } pt; | |
302 | #endif /* defined (HAVE_LIBIPT) */ | |
303 | } variant; | |
304 | }; | |
305 | ||
02d27625 MM |
306 | /* Branch trace information per thread. |
307 | ||
308 | This represents the branch trace configuration as well as the entry point | |
309 | into the branch trace data. For the latter, it also contains the index into | |
310 | an array of branch trace blocks used for iterating though the branch trace | |
311 | blocks of a thread. */ | |
312 | struct btrace_thread_info | |
313 | { | |
314 | /* The target branch trace information for this thread. | |
315 | ||
316 | This contains the branch trace configuration as well as any | |
317 | target-specific information necessary for implementing branch tracing on | |
318 | the underlying architecture. */ | |
319 | struct btrace_target_info *target; | |
320 | ||
9be54cae MM |
321 | /* The raw branch trace data for the below branch trace. */ |
322 | struct btrace_data data; | |
323 | ||
23a7fe75 MM |
324 | /* The current branch trace for this thread (both inclusive). |
325 | ||
326 | The last instruction of END is the current instruction, which is not | |
327 | part of the execution history. | |
328 | Both will be NULL if there is no branch trace available. If there is | |
329 | branch trace available, both will be non-NULL. */ | |
330 | struct btrace_function *begin; | |
331 | struct btrace_function *end; | |
332 | ||
333 | /* The function level offset. When added to each function's LEVEL, | |
334 | this normalizes the function levels such that the smallest level | |
335 | becomes zero. */ | |
336 | int level; | |
02d27625 | 337 | |
31fd9caa MM |
338 | /* The number of gaps in the trace. */ |
339 | unsigned int ngaps; | |
340 | ||
52834460 MM |
341 | /* A bit-vector of btrace_thread_flag. */ |
342 | enum btrace_thread_flag flags; | |
343 | ||
02d27625 | 344 | /* The instruction history iterator. */ |
23a7fe75 | 345 | struct btrace_insn_history *insn_history; |
02d27625 MM |
346 | |
347 | /* The function call history iterator. */ | |
23a7fe75 | 348 | struct btrace_call_history *call_history; |
07bbe694 | 349 | |
31fd9caa MM |
350 | /* The current replay position. NULL if not replaying. |
351 | Gaps are skipped during replay, so REPLAY always points to a valid | |
352 | instruction. */ | |
07bbe694 | 353 | struct btrace_insn_iterator *replay; |
9e8915c6 PA |
354 | |
355 | /* Why the thread stopped, if we need to track it. */ | |
356 | enum target_stop_reason stop_reason; | |
b0627500 MM |
357 | |
358 | /* Maintenance information. */ | |
359 | struct btrace_maint_info maint; | |
02d27625 MM |
360 | }; |
361 | ||
362 | /* Enable branch tracing for a thread. */ | |
f4abbc16 MM |
363 | extern void btrace_enable (struct thread_info *tp, |
364 | const struct btrace_config *conf); | |
365 | ||
366 | /* Get the branch trace configuration for a thread. | |
367 | Return NULL if branch tracing is not enabled for that thread. */ | |
368 | extern const struct btrace_config * | |
369 | btrace_conf (const struct btrace_thread_info *); | |
02d27625 MM |
370 | |
371 | /* Disable branch tracing for a thread. | |
372 | This will also delete the current branch trace data. */ | |
373 | extern void btrace_disable (struct thread_info *); | |
374 | ||
375 | /* Disable branch tracing for a thread during teardown. | |
376 | This is similar to btrace_disable, except that it will use | |
377 | target_teardown_btrace instead of target_disable_btrace. */ | |
378 | extern void btrace_teardown (struct thread_info *); | |
379 | ||
380 | /* Fetch the branch trace for a single thread. */ | |
381 | extern void btrace_fetch (struct thread_info *); | |
382 | ||
383 | /* Clear the branch trace for a single thread. */ | |
384 | extern void btrace_clear (struct thread_info *); | |
385 | ||
386 | /* Clear the branch trace for all threads when an object file goes away. */ | |
387 | extern void btrace_free_objfile (struct objfile *); | |
388 | ||
734b0e4b MM |
389 | /* Parse a branch trace xml document XML into DATA. */ |
390 | extern void parse_xml_btrace (struct btrace_data *data, const char *xml); | |
c12a2917 | 391 | |
f4abbc16 MM |
392 | /* Parse a branch trace configuration xml document XML into CONF. */ |
393 | extern void parse_xml_btrace_conf (struct btrace_config *conf, const char *xml); | |
394 | ||
23a7fe75 | 395 | /* Dereference a branch trace instruction iterator. Return a pointer to the |
31fd9caa MM |
396 | instruction the iterator points to. |
397 | May return NULL if the iterator points to a gap in the trace. */ | |
23a7fe75 MM |
398 | extern const struct btrace_insn * |
399 | btrace_insn_get (const struct btrace_insn_iterator *); | |
400 | ||
401 | /* Return the instruction number for a branch trace iterator. | |
402 | Returns one past the maximum instruction number for the end iterator. | |
403 | Returns zero if the iterator does not point to a valid instruction. */ | |
404 | extern unsigned int btrace_insn_number (const struct btrace_insn_iterator *); | |
405 | ||
406 | /* Initialize a branch trace instruction iterator to point to the begin/end of | |
407 | the branch trace. Throws an error if there is no branch trace. */ | |
408 | extern void btrace_insn_begin (struct btrace_insn_iterator *, | |
409 | const struct btrace_thread_info *); | |
410 | extern void btrace_insn_end (struct btrace_insn_iterator *, | |
411 | const struct btrace_thread_info *); | |
412 | ||
413 | /* Increment/decrement a branch trace instruction iterator by at most STRIDE | |
414 | instructions. Return the number of instructions by which the instruction | |
415 | iterator has been advanced. | |
416 | Returns zero, if the operation failed or STRIDE had been zero. */ | |
417 | extern unsigned int btrace_insn_next (struct btrace_insn_iterator *, | |
418 | unsigned int stride); | |
419 | extern unsigned int btrace_insn_prev (struct btrace_insn_iterator *, | |
420 | unsigned int stride); | |
421 | ||
422 | /* Compare two branch trace instruction iterators. | |
423 | Return a negative number if LHS < RHS. | |
424 | Return zero if LHS == RHS. | |
425 | Return a positive number if LHS > RHS. */ | |
426 | extern int btrace_insn_cmp (const struct btrace_insn_iterator *lhs, | |
427 | const struct btrace_insn_iterator *rhs); | |
428 | ||
429 | /* Find an instruction in the function branch trace by its number. | |
430 | If the instruction is found, initialize the branch trace instruction | |
431 | iterator to point to this instruction and return non-zero. | |
432 | Return zero otherwise. */ | |
433 | extern int btrace_find_insn_by_number (struct btrace_insn_iterator *, | |
434 | const struct btrace_thread_info *, | |
435 | unsigned int number); | |
436 | ||
437 | /* Dereference a branch trace call iterator. Return a pointer to the | |
438 | function the iterator points to or NULL if the interator points past | |
439 | the end of the branch trace. */ | |
440 | extern const struct btrace_function * | |
441 | btrace_call_get (const struct btrace_call_iterator *); | |
442 | ||
443 | /* Return the function number for a branch trace call iterator. | |
444 | Returns one past the maximum function number for the end iterator. | |
445 | Returns zero if the iterator does not point to a valid function. */ | |
446 | extern unsigned int btrace_call_number (const struct btrace_call_iterator *); | |
447 | ||
448 | /* Initialize a branch trace call iterator to point to the begin/end of | |
449 | the branch trace. Throws an error if there is no branch trace. */ | |
450 | extern void btrace_call_begin (struct btrace_call_iterator *, | |
451 | const struct btrace_thread_info *); | |
452 | extern void btrace_call_end (struct btrace_call_iterator *, | |
453 | const struct btrace_thread_info *); | |
454 | ||
455 | /* Increment/decrement a branch trace call iterator by at most STRIDE function | |
456 | segments. Return the number of function segments by which the call | |
457 | iterator has been advanced. | |
458 | Returns zero, if the operation failed or STRIDE had been zero. */ | |
459 | extern unsigned int btrace_call_next (struct btrace_call_iterator *, | |
460 | unsigned int stride); | |
461 | extern unsigned int btrace_call_prev (struct btrace_call_iterator *, | |
462 | unsigned int stride); | |
463 | ||
464 | /* Compare two branch trace call iterators. | |
465 | Return a negative number if LHS < RHS. | |
466 | Return zero if LHS == RHS. | |
467 | Return a positive number if LHS > RHS. */ | |
468 | extern int btrace_call_cmp (const struct btrace_call_iterator *lhs, | |
469 | const struct btrace_call_iterator *rhs); | |
470 | ||
471 | /* Find a function in the function branch trace by its NUMBER. | |
472 | If the function is found, initialize the branch trace call | |
473 | iterator to point to this function and return non-zero. | |
474 | Return zero otherwise. */ | |
475 | extern int btrace_find_call_by_number (struct btrace_call_iterator *, | |
476 | const struct btrace_thread_info *, | |
477 | unsigned int number); | |
478 | ||
479 | /* Set the branch trace instruction history from BEGIN (inclusive) to | |
480 | END (exclusive). */ | |
481 | extern void btrace_set_insn_history (struct btrace_thread_info *, | |
482 | const struct btrace_insn_iterator *begin, | |
483 | const struct btrace_insn_iterator *end); | |
484 | ||
485 | /* Set the branch trace function call history from BEGIN (inclusive) to | |
486 | END (exclusive). */ | |
487 | extern void btrace_set_call_history (struct btrace_thread_info *, | |
488 | const struct btrace_call_iterator *begin, | |
489 | const struct btrace_call_iterator *end); | |
490 | ||
07bbe694 MM |
491 | /* Determine if branch tracing is currently replaying TP. */ |
492 | extern int btrace_is_replaying (struct thread_info *tp); | |
493 | ||
6e07b1d2 MM |
494 | /* Return non-zero if the branch trace for TP is empty; zero otherwise. */ |
495 | extern int btrace_is_empty (struct thread_info *tp); | |
496 | ||
734b0e4b MM |
497 | /* Create a cleanup for DATA. */ |
498 | extern struct cleanup *make_cleanup_btrace_data (struct btrace_data *data); | |
6e07b1d2 | 499 | |
02d27625 | 500 | #endif /* BTRACE_H */ |