GDB (xrefs)
Loading...
Searching...
No Matches
btrace.h
Go to the documentation of this file.
1/* Branch trace support for GDB, the GNU debugger.
2
3 Copyright (C) 2013-2023 Free Software Foundation, Inc.
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 "gdbsupport/btrace-common.h"
30#include "target/waitstatus.h"
31#include "gdbsupport/enum-flags.h"
32
33#if defined (HAVE_LIBIPT)
34# include <intel-pt.h>
35#endif
36
37#include <vector>
38
39struct thread_info;
40struct btrace_function;
41
42/* A coarse instruction classification. */
44{
45 /* The instruction is something not listed below. */
47
48 /* The instruction is a function call. */
50
51 /* The instruction is a function return. */
53
54 /* The instruction is an unconditional jump. */
56};
57
58/* Instruction flags. */
60{
61 /* The instruction has been executed speculatively. */
63};
64DEF_ENUM_FLAGS_TYPE (enum btrace_insn_flag, btrace_insn_flags);
65
66/* A branch trace instruction.
67
68 This represents a single instruction in a branch trace. */
70{
71 /* The address of this instruction. */
72 CORE_ADDR pc;
73
74 /* The size of this instruction in bytes. */
75 gdb_byte size;
76
77 /* The instruction class of this instruction. */
79
80 /* A bit vector of BTRACE_INSN_FLAGS. */
81 btrace_insn_flags flags;
82};
83
84/* Flags for btrace function segments. */
86{
87 /* The 'up' link interpretation.
88 If set, it points to the function segment we returned to.
89 If clear, it points to the function segment we called from. */
91
92 /* The 'up' link points to a tail call. This obviously only makes sense
93 if bfun_up_links_to_ret is clear. */
95};
96DEF_ENUM_FLAGS_TYPE (enum btrace_function_flag, btrace_function_flags);
97
98/* Decode errors for the BTS recording format. */
100{
101 /* The instruction trace overflowed the end of the trace block. */
103
104 /* The instruction size could not be determined. */
107
108/* Decode errors for the Intel Processor Trace recording format. */
110{
111 /* The user cancelled trace processing. */
113
114 /* Tracing was temporarily disabled. */
116
117 /* Trace recording overflowed. */
119
120 /* Negative numbers are used by the decoder library. */
122
123/* A branch trace function segment.
124
125 This represents a function segment in a branch trace, i.e. a consecutive
126 number of instructions belonging to the same function.
127
128 In case of decode errors, we add an empty function segment to indicate
129 the gap in the trace.
130
131 We do not allow function segments without instructions otherwise. */
133{
134 btrace_function (struct minimal_symbol *msym_, struct symbol *sym_,
135 unsigned int number_, unsigned int insn_offset_, int level_)
136 : msym (msym_), sym (sym_), insn_offset (insn_offset_), number (number_),
137 level (level_)
138 {
139 }
140
141 /* The full and minimal symbol for the function. Both may be NULL. */
143 struct symbol *sym;
144
145 /* The function segment numbers of the previous and next segment belonging to
146 the same function. If a function calls another function, the former will
147 have at least two segments: one before the call and another after the
148 return. Will be zero if there is no such function segment. */
149 unsigned int prev = 0;
150 unsigned int next = 0;
151
152 /* The function segment number of the directly preceding function segment in
153 a (fake) call stack. Will be zero if there is no such function segment in
154 the record. */
155 unsigned int up = 0;
156
157 /* The instructions in this function segment.
158 The instruction vector will be empty if the function segment
159 represents a decode error. */
160 std::vector<btrace_insn> insn;
161
162 /* The error code of a decode error that led to a gap.
163 Must be zero unless INSN is empty; non-zero otherwise. */
164 int errcode = 0;
165
166 /* The instruction number offset for the first instruction in this
167 function segment.
168 If INSN is empty this is the insn_offset of the succeding function
169 segment in control-flow order. */
170 unsigned int insn_offset;
171
172 /* The 1-based function number in control-flow order.
173 If INSN is empty indicating a gap in the trace due to a decode error,
174 we still count the gap as a function. */
175 unsigned int number;
176
177 /* The function level in a back trace across the entire branch trace.
178 A caller's level is one lower than the level of its callee.
179
180 Levels can be negative if we see returns for which we have not seen
181 the corresponding calls. The branch trace thread information provides
182 a fixup to normalize function levels so the smallest level is zero. */
183 int level;
184
185 /* A bit-vector of btrace_function_flag. */
186 btrace_function_flags flags = 0;
187};
188
189/* A branch trace instruction iterator. */
191{
192 /* The branch trace information for this thread. Will never be NULL. */
194
195 /* The index of the function segment in BTINFO->FUNCTIONS. */
196 unsigned int call_index;
197
198 /* The index into the function segment's instruction vector. */
199 unsigned int insn_index;
200};
201
202/* A branch trace function call iterator. */
204{
205 /* The branch trace information for this thread. Will never be NULL. */
207
208 /* The index of the function segment in BTINFO->FUNCTIONS. */
209 unsigned int index;
210};
211
212/* Branch trace iteration state for "record instruction-history". */
214{
215 /* The branch trace instruction range from BEGIN (inclusive) to
216 END (exclusive) that has been covered last time. */
219};
220
221/* Branch trace iteration state for "record function-call-history". */
223{
224 /* The branch trace function range from BEGIN (inclusive) to END (exclusive)
225 that has been covered last time. */
228};
229
230/* Branch trace thread flags. */
231enum btrace_thread_flag : unsigned
232{
233 /* The thread is to be stepped forwards. */
234 BTHR_STEP = (1 << 0),
235
236 /* The thread is to be stepped backwards. */
237 BTHR_RSTEP = (1 << 1),
238
239 /* The thread is to be continued forwards. */
240 BTHR_CONT = (1 << 2),
241
242 /* The thread is to be continued backwards. */
243 BTHR_RCONT = (1 << 3),
244
245 /* The thread is to be moved. */
247
248 /* The thread is to be stopped. */
249 BTHR_STOP = (1 << 4)
251DEF_ENUM_FLAGS_TYPE (enum btrace_thread_flag, btrace_thread_flags);
252
253#if defined (HAVE_LIBIPT)
254/* A packet. */
255struct btrace_pt_packet
256{
257 /* The offset in the trace stream. */
258 uint64_t offset;
259
260 /* The decode error code. */
261 enum pt_error_code errcode;
262
263 /* The decoded packet. Only valid if ERRCODE == pte_ok. */
264 struct pt_packet packet;
265};
266
267#endif /* defined (HAVE_LIBIPT) */
268
269/* Branch trace iteration state for "maintenance btrace packet-history". */
271{
272 /* The branch trace packet range from BEGIN (inclusive) to
273 END (exclusive) that has been covered last time. */
274 unsigned int begin;
275 unsigned int end;
276};
277
278/* Branch trace maintenance information per thread.
279
280 This information is used by "maintenance btrace" commands. */
282{
283 /* Most information is format-specific.
284 The format can be found in the BTRACE.DATA.FORMAT field of each thread. */
285 union
286 {
287 /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_BTS */
288 struct
289 {
290 /* The packet history iterator.
291 We are iterating over BTRACE.DATA.FORMAT.VARIANT.BTS.BLOCKS. */
294
295#if defined (HAVE_LIBIPT)
296 /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_PT */
297 struct
298 {
299 /* A vector of decoded packets. */
300 std::vector<btrace_pt_packet> *packets;
301
302 /* The packet history iterator.
303 We are iterating over the above PACKETS vector. */
305 } pt;
306#endif /* defined (HAVE_LIBIPT) */
308};
309
310/* Branch trace information per thread.
311
312 This represents the branch trace configuration as well as the entry point
313 into the branch trace data. For the latter, it also contains the index into
314 an array of branch trace blocks used for iterating though the branch trace
315 blocks of a thread. */
317{
318 /* The target branch trace information for this thread.
319
320 This contains the branch trace configuration as well as any
321 target-specific information necessary for implementing branch tracing on
322 the underlying architecture. */
323 struct btrace_target_info *target;
324
325 /* The raw branch trace data for the below branch trace. */
326 struct btrace_data data;
327
328 /* Vector of decoded function segments in execution flow order.
329 Note that the numbering for btrace function segments starts with 1, so
330 function segment i will be at index (i - 1). */
331 std::vector<btrace_function> functions;
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;
337
338 /* The number of gaps in the trace. */
339 unsigned int ngaps;
340
341 /* A bit-vector of btrace_thread_flag. */
342 btrace_thread_flags flags;
343
344 /* The instruction history iterator. */
346
347 /* The function call history iterator. */
349
350 /* The current replay position. NULL if not replaying.
351 Gaps are skipped during replay, so REPLAY always points to a valid
352 instruction. */
354
355 /* Why the thread stopped, if we need to track it. */
357
358 /* Maintenance information. */
360};
361
362/* Enable branch tracing for a thread. */
363extern 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. */
368extern const struct btrace_config *
369 btrace_conf (const struct btrace_thread_info *);
370
371/* Disable branch tracing for a thread.
372 This will also delete the current branch trace data. */
373extern 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. */
378extern void btrace_teardown (struct thread_info *);
379
380/* Return a human readable error string for the given ERRCODE in FORMAT.
381 The pointer will never be NULL and must not be freed. */
382
383extern const char *btrace_decode_error (enum btrace_format format, int errcode);
384
385/* Fetch the branch trace for a single thread. If CPU is not NULL, assume
386 CPU for trace decode. */
387extern void btrace_fetch (struct thread_info *,
388 const struct btrace_cpu *cpu);
389
390/* Clear the branch trace for a single thread. */
391extern void btrace_clear (struct thread_info *);
392
393/* Clear the branch trace for all threads when an object file goes away. */
394extern void btrace_free_objfile (struct objfile *);
395
396/* Dereference a branch trace instruction iterator. Return a pointer to the
397 instruction the iterator points to.
398 May return NULL if the iterator points to a gap in the trace. */
399extern const struct btrace_insn *
400 btrace_insn_get (const struct btrace_insn_iterator *);
401
402/* Return the error code for a branch trace instruction iterator. Returns zero
403 if there is no error, i.e. the instruction is valid. */
404extern int btrace_insn_get_error (const struct btrace_insn_iterator *);
405
406/* Return the instruction number for a branch trace iterator.
407 Returns one past the maximum instruction number for the end iterator. */
408extern unsigned int btrace_insn_number (const struct btrace_insn_iterator *);
409
410/* Initialize a branch trace instruction iterator to point to the begin/end of
411 the branch trace. Throws an error if there is no branch trace. */
412extern void btrace_insn_begin (struct btrace_insn_iterator *,
413 const struct btrace_thread_info *);
414extern void btrace_insn_end (struct btrace_insn_iterator *,
415 const struct btrace_thread_info *);
416
417/* Increment/decrement a branch trace instruction iterator by at most STRIDE
418 instructions. Return the number of instructions by which the instruction
419 iterator has been advanced.
420 Returns zero, if the operation failed or STRIDE had been zero. */
421extern unsigned int btrace_insn_next (struct btrace_insn_iterator *,
422 unsigned int stride);
423extern unsigned int btrace_insn_prev (struct btrace_insn_iterator *,
424 unsigned int stride);
425
426/* Compare two branch trace instruction iterators.
427 Return a negative number if LHS < RHS.
428 Return zero if LHS == RHS.
429 Return a positive number if LHS > RHS. */
430extern int btrace_insn_cmp (const struct btrace_insn_iterator *lhs,
431 const struct btrace_insn_iterator *rhs);
432
433/* Find an instruction or gap in the function branch trace by its number.
434 If the instruction is found, initialize the branch trace instruction
435 iterator to point to this instruction and return non-zero.
436 Return zero otherwise. */
438 const struct btrace_thread_info *,
439 unsigned int number);
440
441/* Dereference a branch trace call iterator. Return a pointer to the
442 function the iterator points to or NULL if the iterator points past
443 the end of the branch trace. */
444extern const struct btrace_function *
445 btrace_call_get (const struct btrace_call_iterator *);
446
447/* Return the function number for a branch trace call iterator.
448 Returns one past the maximum function number for the end iterator.
449 Returns zero if the iterator does not point to a valid function. */
450extern unsigned int btrace_call_number (const struct btrace_call_iterator *);
451
452/* Initialize a branch trace call iterator to point to the begin/end of
453 the branch trace. Throws an error if there is no branch trace. */
454extern void btrace_call_begin (struct btrace_call_iterator *,
455 const struct btrace_thread_info *);
456extern void btrace_call_end (struct btrace_call_iterator *,
457 const struct btrace_thread_info *);
458
459/* Increment/decrement a branch trace call iterator by at most STRIDE function
460 segments. Return the number of function segments by which the call
461 iterator has been advanced.
462 Returns zero, if the operation failed or STRIDE had been zero. */
463extern unsigned int btrace_call_next (struct btrace_call_iterator *,
464 unsigned int stride);
465extern unsigned int btrace_call_prev (struct btrace_call_iterator *,
466 unsigned int stride);
467
468/* Compare two branch trace call iterators.
469 Return a negative number if LHS < RHS.
470 Return zero if LHS == RHS.
471 Return a positive number if LHS > RHS. */
472extern int btrace_call_cmp (const struct btrace_call_iterator *lhs,
473 const struct btrace_call_iterator *rhs);
474
475/* Find a function in the function branch trace by its NUMBER.
476 If the function is found, initialize the branch trace call
477 iterator to point to this function and return non-zero.
478 Return zero otherwise. */
480 const struct btrace_thread_info *,
481 unsigned int number);
482
483/* Set the branch trace instruction history from BEGIN (inclusive) to
484 END (exclusive). */
485extern void btrace_set_insn_history (struct btrace_thread_info *,
486 const struct btrace_insn_iterator *begin,
487 const struct btrace_insn_iterator *end);
488
489/* Set the branch trace function call history from BEGIN (inclusive) to
490 END (exclusive). */
491extern void btrace_set_call_history (struct btrace_thread_info *,
492 const struct btrace_call_iterator *begin,
493 const struct btrace_call_iterator *end);
494
495/* Determine if branch tracing is currently replaying TP. */
496extern int btrace_is_replaying (struct thread_info *tp);
497
498/* Return non-zero if the branch trace for TP is empty; zero otherwise. */
499extern int btrace_is_empty (struct thread_info *tp);
500
501#endif /* BTRACE_H */
void btrace_enable(struct thread_info *tp, const struct btrace_config *conf)
Definition btrace.c:1606
void btrace_disable(struct thread_info *)
Definition btrace.c:1664
unsigned int btrace_call_prev(struct btrace_call_iterator *, unsigned int stride)
Definition btrace.c:2412
btrace_function_flag
Definition btrace.h:86
@ BFUN_UP_LINKS_TO_RET
Definition btrace.h:90
@ BFUN_UP_LINKS_TO_TAILCALL
Definition btrace.h:94
void btrace_insn_end(struct btrace_insn_iterator *, const struct btrace_thread_info *)
Definition btrace.c:2075
void btrace_call_end(struct btrace_call_iterator *, const struct btrace_thread_info *)
Definition btrace.c:2363
btrace_insn_class
Definition btrace.h:44
@ BTRACE_INSN_RETURN
Definition btrace.h:52
@ BTRACE_INSN_JUMP
Definition btrace.h:55
@ BTRACE_INSN_OTHER
Definition btrace.h:46
@ BTRACE_INSN_CALL
Definition btrace.h:49
unsigned int btrace_insn_next(struct btrace_insn_iterator *, unsigned int stride)
Definition btrace.c:2101
int btrace_insn_cmp(const struct btrace_insn_iterator *lhs, const struct btrace_insn_iterator *rhs)
Definition btrace.c:2241
void btrace_call_begin(struct btrace_call_iterator *, const struct btrace_thread_info *)
Definition btrace.c:2350
void btrace_teardown(struct thread_info *)
Definition btrace.c:1684
int btrace_insn_get_error(const struct btrace_insn_iterator *)
Definition btrace.c:2045
btrace_pt_error
Definition btrace.h:110
@ BDE_PT_OVERFLOW
Definition btrace.h:118
@ BDE_PT_USER_QUIT
Definition btrace.h:112
@ BDE_PT_DISABLED
Definition btrace.h:115
int btrace_find_call_by_number(struct btrace_call_iterator *, const struct btrace_thread_info *, unsigned int number)
Definition btrace.c:2456
void btrace_insn_begin(struct btrace_insn_iterator *, const struct btrace_thread_info *)
Definition btrace.c:2061
const char * btrace_decode_error(enum btrace_format format, int errcode)
Definition btrace.c:1857
const struct btrace_config * btrace_conf(const struct btrace_thread_info *)
Definition btrace.c:1653
unsigned int btrace_insn_number(const struct btrace_insn_iterator *)
Definition btrace.c:2053
unsigned int btrace_insn_prev(struct btrace_insn_iterator *, unsigned int stride)
Definition btrace.c:2183
DEF_ENUM_FLAGS_TYPE(enum btrace_insn_flag, btrace_insn_flags)
void btrace_set_insn_history(struct btrace_thread_info *, const struct btrace_insn_iterator *begin, const struct btrace_insn_iterator *end)
Definition btrace.c:2473
int btrace_find_insn_by_number(struct btrace_insn_iterator *, const struct btrace_thread_info *, unsigned int number)
Definition btrace.c:2255
void btrace_fetch(struct thread_info *, const struct btrace_cpu *cpu)
Definition btrace.c:1906
btrace_insn_flag
Definition btrace.h:60
@ BTRACE_INSN_FLAG_SPECULATIVE
Definition btrace.h:62
btrace_thread_flag
Definition btrace.h:232
@ BTHR_CONT
Definition btrace.h:240
@ BTHR_RSTEP
Definition btrace.h:237
@ BTHR_STEP
Definition btrace.h:234
@ BTHR_MOVE
Definition btrace.h:246
@ BTHR_RCONT
Definition btrace.h:243
@ BTHR_STOP
Definition btrace.h:249
btrace_bts_error
Definition btrace.h:100
@ BDE_BTS_OVERFLOW
Definition btrace.h:102
@ BDE_BTS_INSN_SIZE
Definition btrace.h:105
const struct btrace_insn * btrace_insn_get(const struct btrace_insn_iterator *)
Definition btrace.c:2022
void btrace_set_call_history(struct btrace_thread_info *, const struct btrace_call_iterator *begin, const struct btrace_call_iterator *end)
Definition btrace.c:2487
unsigned int btrace_call_next(struct btrace_call_iterator *, unsigned int stride)
Definition btrace.c:2376
unsigned int btrace_call_number(const struct btrace_call_iterator *)
Definition btrace.c:2335
const struct btrace_function * btrace_call_get(const struct btrace_call_iterator *)
Definition btrace.c:2324
void btrace_free_objfile(struct objfile *)
Definition btrace.c:2011
void btrace_clear(struct thread_info *)
Definition btrace.c:1986
int btrace_is_empty(struct thread_info *tp)
Definition btrace.c:2511
int btrace_is_replaying(struct thread_info *tp)
Definition btrace.c:2503
int btrace_call_cmp(const struct btrace_call_iterator *lhs, const struct btrace_call_iterator *rhs)
Definition btrace.c:2446
struct btrace_call_iterator begin
Definition btrace.h:226
struct btrace_call_iterator end
Definition btrace.h:227
unsigned int index
Definition btrace.h:209
const struct btrace_thread_info * btinfo
Definition btrace.h:206
btrace_function_flags flags
Definition btrace.h:186
btrace_function(struct minimal_symbol *msym_, struct symbol *sym_, unsigned int number_, unsigned int insn_offset_, int level_)
Definition btrace.h:134
unsigned int up
Definition btrace.h:155
struct minimal_symbol * msym
Definition btrace.h:142
unsigned int prev
Definition btrace.h:149
unsigned int number
Definition btrace.h:175
std::vector< btrace_insn > insn
Definition btrace.h:160
struct symbol * sym
Definition btrace.h:143
unsigned int insn_offset
Definition btrace.h:170
struct btrace_insn_iterator begin
Definition btrace.h:217
struct btrace_insn_iterator end
Definition btrace.h:218
unsigned int call_index
Definition btrace.h:196
unsigned int insn_index
Definition btrace.h:199
const struct btrace_thread_info * btinfo
Definition btrace.h:193
gdb_byte size
Definition btrace.h:75
btrace_insn_flags flags
Definition btrace.h:81
enum btrace_insn_class iclass
Definition btrace.h:78
CORE_ADDR pc
Definition btrace.h:72
union btrace_maint_info::@22 variant
struct btrace_maint_info::@22::@23 bts
struct btrace_maint_packet_history packet_history
Definition btrace.h:292
unsigned int ngaps
Definition btrace.h:339
struct btrace_target_info * target
Definition btrace.h:323
std::vector< btrace_function > functions
Definition btrace.h:331
btrace_thread_flags flags
Definition btrace.h:342
struct btrace_insn_iterator * replay
Definition btrace.h:353
struct btrace_maint_info maint
Definition btrace.h:359
struct btrace_call_history * call_history
Definition btrace.h:348
enum target_stop_reason stop_reason
Definition btrace.h:356
struct btrace_insn_history * insn_history
Definition btrace.h:345
struct btrace_data data
Definition btrace.h:326
target_stop_reason
Definition waitstatus.h:428