gdb/btrace.h

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