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 previous and next function in control flow order.  */
 155   struct btrace_func_link flow;
 156
 157   /* The function segment number of the directly preceding function segment in
 158      a (fake) call stack.  Will be zero if there is no such function segment in
 159      the record.  */
 160   unsigned int up;
 161
 162   /* The instructions in this function segment.
 163      The instruction vector will be empty if the function segment
 164      represents a decode error.  */
 165   VEC (btrace_insn_s) *insn;
 166
 167   /* The error code of a decode error that led to a gap.
 168      Must be zero unless INSN is empty; non-zero otherwise.  */
 169   int errcode;
 170
 171   /* The instruction number offset for the first instruction in this
 172      function segment.
 173      If INSN is empty this is the insn_offset of the succeding function
 174      segment in control-flow order.  */
 175   unsigned int insn_offset;
 176
 177   /* The 1-based function number in control-flow order.
 178      If INSN is empty indicating a gap in the trace due to a decode error,
 179      we still count the gap as a function.  */
 180   unsigned int number;
 181
 182   /* The function level in a back trace across the entire branch trace.
 183      A caller's level is one lower than the level of its callee.
 184
 185      Levels can be negative if we see returns for which we have not seen
 186      the corresponding calls.  The branch trace thread information provides
 187      a fixup to normalize function levels so the smallest level is zero.  */
 188   int level;
 189
 190   /* A bit-vector of btrace_function_flag.  */
 191   btrace_function_flags flags;
 192 };
 193
 194 /* A branch trace instruction iterator.  */
 195 struct btrace_insn_iterator
 196 {
 197   /* The branch trace information for this thread.  Will never be NULL.  */
 198   const struct btrace_thread_info *btinfo;
 199
 200   /* The index of the function segment in BTINFO->FUNCTIONS.  */
 201   unsigned int call_index;
 202
 203   /* The index into the function segment's instruction vector.  */
 204   unsigned int insn_index;
 205 };
 206
 207 /* A branch trace function call iterator.  */
 208 struct btrace_call_iterator
 209 {
 210   /* The branch trace information for this thread.  Will never be NULL.  */
 211   const struct btrace_thread_info *btinfo;
 212
 213   /* The index of the function segment in BTINFO->FUNCTIONS.  */
 214   unsigned int index;
 215 };
 216
 217 /* Branch trace iteration state for "record instruction-history".  */
 218 struct btrace_insn_history
 219 {
 220   /* The branch trace instruction range from BEGIN (inclusive) to
 221      END (exclusive) that has been covered last time.  */
 222   struct btrace_insn_iterator begin;
 223   struct btrace_insn_iterator end;
 224 };
 225
 226 /* Branch trace iteration state for "record function-call-history".  */
 227 struct btrace_call_history
 228 {
 229   /* The branch trace function range from BEGIN (inclusive) to END (exclusive)
 230      that has been covered last time.  */
 231   struct btrace_call_iterator begin;
 232   struct btrace_call_iterator end;
 233 };
 234
 235 /* Branch trace thread flags.  */
 236 enum btrace_thread_flag
 237 {
 238   /* The thread is to be stepped forwards.  */
 239   BTHR_STEP = (1 << 0),
 240
 241   /* The thread is to be stepped backwards.  */
 242   BTHR_RSTEP = (1 << 1),
 243
 244   /* The thread is to be continued forwards.  */
 245   BTHR_CONT = (1 << 2),
 246
 247   /* The thread is to be continued backwards.  */
 248   BTHR_RCONT = (1 << 3),
 249
 250   /* The thread is to be moved.  */
 251   BTHR_MOVE = (BTHR_STEP | BTHR_RSTEP | BTHR_CONT | BTHR_RCONT),
 252
 253   /* The thread is to be stopped.  */
 254   BTHR_STOP = (1 << 4)
 255 };
 256 DEF_ENUM_FLAGS_TYPE (enum btrace_thread_flag, btrace_thread_flags);
 257
 258 #if defined (HAVE_LIBIPT)
 259 /* A packet.  */
 260 struct btrace_pt_packet
 261 {
 262   /* The offset in the trace stream.  */
 263   uint64_t offset;
 264
 265   /* The decode error code.  */
 266   enum pt_error_code errcode;
 267
 268   /* The decoded packet.  Only valid if ERRCODE == pte_ok.  */
 269   struct pt_packet packet;
 270 };
 271
 272 /* Define functions operating on a vector of packets.  */
 273 typedef struct btrace_pt_packet btrace_pt_packet_s;
 274 DEF_VEC_O (btrace_pt_packet_s);
 275 #endif /* defined (HAVE_LIBIPT)  */
 276
 277 /* Branch trace iteration state for "maintenance btrace packet-history".  */
 278 struct btrace_maint_packet_history
 279 {
 280   /* The branch trace packet range from BEGIN (inclusive) to
 281      END (exclusive) that has been covered last time.  */
 282   unsigned int begin;
 283   unsigned int end;
 284 };
 285
 286 /* Branch trace maintenance information per thread.
 287
 288    This information is used by "maintenance btrace" commands.  */
 289 struct btrace_maint_info
 290 {
 291   /* Most information is format-specific.
 292      The format can be found in the BTRACE.DATA.FORMAT field of each thread.  */
 293   union
 294   {
 295     /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_BTS  */
 296     struct
 297     {
 298       /* The packet history iterator.
 299          We are iterating over BTRACE.DATA.FORMAT.VARIANT.BTS.BLOCKS.  */
 300       struct btrace_maint_packet_history packet_history;
 301     } bts;
 302
 303 #if defined (HAVE_LIBIPT)
 304     /* BTRACE.DATA.FORMAT == BTRACE_FORMAT_PT  */
 305     struct
 306     {
 307       /* A vector of decoded packets.  */
 308       VEC (btrace_pt_packet_s) *packets;
 309
 310       /* The packet history iterator.
 311          We are iterating over the above PACKETS vector.  */
 312       struct btrace_maint_packet_history packet_history;
 313     } pt;
 314 #endif /* defined (HAVE_LIBIPT)  */
 315   } variant;
 316 };
 317
 318 /* Branch trace information per thread.
 319
 320    This represents the branch trace configuration as well as the entry point
 321    into the branch trace data.  For the latter, it also contains the index into
 322    an array of branch trace blocks used for iterating though the branch trace
 323    blocks of a thread.  */
 324 struct btrace_thread_info
 325 {
 326   /* The target branch trace information for this thread.
 327
 328      This contains the branch trace configuration as well as any
 329      target-specific information necessary for implementing branch tracing on
 330      the underlying architecture.  */
 331   struct btrace_target_info *target;
 332
 333   /* The raw branch trace data for the below branch trace.  */
 334   struct btrace_data data;
 335
 336   /* Vector of pointer to decoded function segments in execution flow order.
 337      Note that the numbering for btrace function segments starts with 1, so
 338      function segment i will be at index (i - 1).  */
 339   std::vector<btrace_function *> functions;
 340
 341   /* The function level offset.  When added to each function's LEVEL,
 342      this normalizes the function levels such that the smallest level
 343      becomes zero.  */
 344   int level;
 345
 346   /* The number of gaps in the trace.  */
 347   unsigned int ngaps;
 348
 349   /* A bit-vector of btrace_thread_flag.  */
 350   btrace_thread_flags flags;
 351
 352   /* The instruction history iterator.  */
 353   struct btrace_insn_history *insn_history;
 354
 355   /* The function call history iterator.  */
 356   struct btrace_call_history *call_history;
 357
 358   /* The current replay position.  NULL if not replaying.
 359      Gaps are skipped during replay, so REPLAY always points to a valid
 360      instruction.  */
 361   struct btrace_insn_iterator *replay;
 362
 363   /* Why the thread stopped, if we need to track it.  */
 364   enum target_stop_reason stop_reason;
 365
 366   /* Maintenance information.  */
 367   struct btrace_maint_info maint;
 368 };
 369
 370 /* Enable branch tracing for a thread.  */
 371 extern void btrace_enable (struct thread_info *tp,
 372                            const struct btrace_config *conf);
 373
 374 /* Get the branch trace configuration for a thread.
 375    Return NULL if branch tracing is not enabled for that thread.  */
 376 extern const struct btrace_config *
 377   btrace_conf (const struct btrace_thread_info *);
 378
 379 /* Disable branch tracing for a thread.
 380    This will also delete the current branch trace data.  */
 381 extern void btrace_disable (struct thread_info *);
 382
 383 /* Disable branch tracing for a thread during teardown.
 384    This is similar to btrace_disable, except that it will use
 385    target_teardown_btrace instead of target_disable_btrace.  */
 386 extern void btrace_teardown (struct thread_info *);
 387
 388 /* Return a human readable error string for the given ERRCODE in FORMAT.
 389    The pointer will never be NULL and must not be freed.  */
 390
 391 extern const char *btrace_decode_error (enum btrace_format format, int errcode);
 392
 393 /* Fetch the branch trace for a single thread.  */
 394 extern void btrace_fetch (struct thread_info *);
 395
 396 /* Clear the branch trace for a single thread.  */
 397 extern void btrace_clear (struct thread_info *);
 398
 399 /* Clear the branch trace for all threads when an object file goes away.  */
 400 extern void btrace_free_objfile (struct objfile *);
 401
 402 /* Parse a branch trace xml document XML into DATA.  */
 403 extern void parse_xml_btrace (struct btrace_data *data, const char *xml);
 404
 405 /* Parse a branch trace configuration xml document XML into CONF.  */
 406 extern void parse_xml_btrace_conf (struct btrace_config *conf, const char *xml);
 407
 408 /* Dereference a branch trace instruction iterator.  Return a pointer to the
 409    instruction the iterator points to.
 410    May return NULL if the iterator points to a gap in the trace.  */
 411 extern const struct btrace_insn *
 412   btrace_insn_get (const struct btrace_insn_iterator *);
 413
 414 /* Return the error code for a branch trace instruction iterator.  Returns zero
 415    if there is no error, i.e. the instruction is valid.  */
 416 extern int btrace_insn_get_error (const struct btrace_insn_iterator *);
 417
 418 /* Return the instruction number for a branch trace iterator.
 419    Returns one past the maximum instruction number for the end iterator.  */
 420 extern unsigned int btrace_insn_number (const struct btrace_insn_iterator *);
 421
 422 /* Initialize a branch trace instruction iterator to point to the begin/end of
 423    the branch trace.  Throws an error if there is no branch trace.  */
 424 extern void btrace_insn_begin (struct btrace_insn_iterator *,
 425                                const struct btrace_thread_info *);
 426 extern void btrace_insn_end (struct btrace_insn_iterator *,
 427                              const struct btrace_thread_info *);
 428
 429 /* Increment/decrement a branch trace instruction iterator by at most STRIDE
 430    instructions.  Return the number of instructions by which the instruction
 431    iterator has been advanced.
 432    Returns zero, if the operation failed or STRIDE had been zero.  */
 433 extern unsigned int btrace_insn_next (struct btrace_insn_iterator *,
 434                                       unsigned int stride);
 435 extern unsigned int btrace_insn_prev (struct btrace_insn_iterator *,
 436                                       unsigned int stride);
 437
 438 /* Compare two branch trace instruction iterators.
 439    Return a negative number if LHS < RHS.
 440    Return zero if LHS == RHS.
 441    Return a positive number if LHS > RHS.  */
 442 extern int btrace_insn_cmp (const struct btrace_insn_iterator *lhs,
 443                             const struct btrace_insn_iterator *rhs);
 444
 445 /* Find an instruction or gap in the function branch trace by its number.
 446    If the instruction is found, initialize the branch trace instruction
 447    iterator to point to this instruction and return non-zero.
 448    Return zero otherwise.  */
 449 extern int btrace_find_insn_by_number (struct btrace_insn_iterator *,
 450                                        const struct btrace_thread_info *,
 451                                        unsigned int number);
 452
 453 /* Dereference a branch trace call iterator.  Return a pointer to the
 454    function the iterator points to or NULL if the interator points past
 455    the end of the branch trace.  */
 456 extern const struct btrace_function *
 457   btrace_call_get (const struct btrace_call_iterator *);
 458
 459 /* Return the function number for a branch trace call iterator.
 460    Returns one past the maximum function number for the end iterator.
 461    Returns zero if the iterator does not point to a valid function.  */
 462 extern unsigned int btrace_call_number (const struct btrace_call_iterator *);
 463
 464 /* Initialize a branch trace call iterator to point to the begin/end of
 465    the branch trace.  Throws an error if there is no branch trace.  */
 466 extern void btrace_call_begin (struct btrace_call_iterator *,
 467                                const struct btrace_thread_info *);
 468 extern void btrace_call_end (struct btrace_call_iterator *,
 469                              const struct btrace_thread_info *);
 470
 471 /* Increment/decrement a branch trace call iterator by at most STRIDE function
 472    segments.  Return the number of function segments by which the call
 473    iterator has been advanced.
 474    Returns zero, if the operation failed or STRIDE had been zero.  */
 475 extern unsigned int btrace_call_next (struct btrace_call_iterator *,
 476                                       unsigned int stride);
 477 extern unsigned int btrace_call_prev (struct btrace_call_iterator *,
 478                                       unsigned int stride);
 479
 480 /* Compare two branch trace call iterators.
 481    Return a negative number if LHS < RHS.
 482    Return zero if LHS == RHS.
 483    Return a positive number if LHS > RHS.  */
 484 extern int btrace_call_cmp (const struct btrace_call_iterator *lhs,
 485                             const struct btrace_call_iterator *rhs);
 486
 487 /* Find a function in the function branch trace by its NUMBER.
 488    If the function is found, initialize the branch trace call
 489    iterator to point to this function and return non-zero.
 490    Return zero otherwise.  */
 491 extern int btrace_find_call_by_number (struct btrace_call_iterator *,
 492                                        const struct btrace_thread_info *,
 493                                        unsigned int number);
 494
 495 /* Set the branch trace instruction history from BEGIN (inclusive) to
 496    END (exclusive).  */
 497 extern void btrace_set_insn_history (struct btrace_thread_info *,
 498                                      const struct btrace_insn_iterator *begin,
 499                                      const struct btrace_insn_iterator *end);
 500
 501 /* Set the branch trace function call history from BEGIN (inclusive) to
 502    END (exclusive).  */
 503 extern void btrace_set_call_history (struct btrace_thread_info *,
 504                                      const struct btrace_call_iterator *begin,
 505                                      const struct btrace_call_iterator *end);
 506
 507 /* Determine if branch tracing is currently replaying TP.  */
 508 extern int btrace_is_replaying (struct thread_info *tp);
 509
 510 /* Return non-zero if the branch trace for TP is empty; zero otherwise.  */
 511 extern int btrace_is_empty (struct thread_info *tp);
 512
 513 /* Create a cleanup for DATA.  */
 514 extern struct cleanup *make_cleanup_btrace_data (struct btrace_data *data);
 515
 516 #endif /* BTRACE_H */