gdb/btrace.h

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