gdbsupport/btrace-common.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 COMMON_BTRACE_COMMON_H
  23 #define COMMON_BTRACE_COMMON_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 /* A branch trace block.
  30
  31    This represents a block of sequential control-flow.  Adjacent blocks will be
  32    connected via calls, returns, or jumps.  The latter can be direct or
  33    indirect, conditional or unconditional.  Branches can further be
  34    asynchronous, e.g. interrupts.  */
  35 struct btrace_block
  36 {
  37   /* The address of the first byte of the first instruction in the block.
  38      The address may be zero if we do not know the beginning of this block,
  39      such as for the first block in a delta trace.  */
  40   CORE_ADDR begin;
  41
  42   /* The address of the first byte of the last instruction in the block.  */
  43   CORE_ADDR end;
  44
  45   /* Simple constructor.  */
  46   btrace_block (CORE_ADDR begin, CORE_ADDR end)
  47     : begin (begin),
  48       end (end)
  49   {
  50     /* Nothing.  */
  51   }
  52 };
  53
  54 /* Enumeration of btrace formats.  */
  55
  56 enum btrace_format
  57 {
  58   /* No branch trace format.  */
  59   BTRACE_FORMAT_NONE,
  60
  61   /* Branch trace is in Branch Trace Store (BTS) format.
  62      Actually, the format is a sequence of blocks derived from BTS.  */
  63   BTRACE_FORMAT_BTS,
  64
  65   /* Branch trace is in Intel Processor Trace format.  */
  66   BTRACE_FORMAT_PT
  67 };
  68
  69 /* An enumeration of cpu vendors.  */
  70
  71 enum btrace_cpu_vendor
  72 {
  73   /* We do not know this vendor.  */
  74   CV_UNKNOWN,
  75
  76   /* Intel.  */
  77   CV_INTEL,
  78
  79   /* AMD.  */
  80   CV_AMD
  81 };
  82
  83 /* A cpu identifier.  */
  84
  85 struct btrace_cpu
  86 {
  87   /* The processor vendor.  */
  88   enum btrace_cpu_vendor vendor;
  89
  90   /* The cpu family.  */
  91   unsigned short family;
  92
  93   /* The cpu model.  */
  94   unsigned char model;
  95
  96   /* The cpu stepping.  */
  97   unsigned char stepping;
  98 };
  99
 100 /* A BTS configuration.  */
 101
 102 struct btrace_config_bts
 103 {
 104   /* The size of the branch trace buffer in bytes.
 105
 106      This is unsigned int and not size_t since it is registered as
 107      control variable for "set record btrace bts buffer-size".  */
 108   unsigned int size;
 109 };
 110
 111 /* An Intel Processor Trace configuration.  */
 112
 113 struct btrace_config_pt
 114 {
 115   /* The size of the branch trace buffer in bytes.
 116
 117      This is unsigned int and not size_t since it is registered as
 118      control variable for "set record btrace pt buffer-size".  */
 119   unsigned int size;
 120
 121   /* Configuration bit for ptwrite packets.
 122
 123      If both gdb and gdbserver support this, gdb will try to enable ptwrite
 124      packets when tracing is started.  */
 125   bool ptwrite;
 126
 127   /* Event tracing setting.  */
 128   bool event_tracing;
 129 };
 130
 131 /* A branch tracing configuration.
 132
 133    This describes the requested configuration as well as the actually
 134    obtained configuration.
 135    We describe the configuration for all different formats so we can
 136    easily switch between formats.  */
 137
 138 struct btrace_config
 139 {
 140   /* The branch tracing format.  */
 141   enum btrace_format format;
 142
 143   /* The BTS format configuration.  */
 144   struct btrace_config_bts bts;
 145
 146   /* The Intel Processor Trace format configuration.  */
 147   struct btrace_config_pt pt;
 148 };
 149
 150 /* Branch trace in BTS format.  */
 151 struct btrace_data_bts
 152 {
 153   /* Branch trace is represented as a vector of branch trace blocks starting
 154      with the most recent block.  This needs to be a pointer as we place
 155      btrace_data_bts into a union.  */
 156   std::vector<btrace_block> *blocks;
 157 };
 158
 159 /* Configuration information to go with the trace data.  */
 160 struct btrace_data_pt_config
 161 {
 162   /* The processor on which the trace has been collected.  */
 163   struct btrace_cpu cpu;
 164 };
 165
 166 /* Branch trace in Intel Processor Trace format.  */
 167 struct btrace_data_pt
 168 {
 169   /* Some configuration information to go with the data.  */
 170   struct btrace_data_pt_config config;
 171
 172   /* The trace data.  */
 173   gdb_byte *data;
 174
 175   /* The size of DATA in bytes.  */
 176   size_t size;
 177 };
 178
 179 /* The branch trace data.  */
 180 struct btrace_data
 181 {
 182   btrace_data () = default;
 183
 184   ~btrace_data ()
 185   {
 186     fini ();
 187   }
 188
 189   btrace_data &operator= (btrace_data &&other)
 190   {
 191     if (this != &other)
 192       {
 193         fini ();
 194         format = other.format;
 195         variant = other.variant;
 196         other.format = BTRACE_FORMAT_NONE;
 197       }
 198     return *this;
 199   }
 200
 201   /* Return true if this is empty; false otherwise.  */
 202   bool empty () const;
 203
 204   /* Clear this object.  */
 205   void clear ();
 206
 207   enum btrace_format format = BTRACE_FORMAT_NONE;
 208
 209   union
 210   {
 211     /* Format == BTRACE_FORMAT_BTS.  */
 212     struct btrace_data_bts bts;
 213
 214     /* Format == BTRACE_FORMAT_PT.  */
 215     struct btrace_data_pt pt;
 216   } variant;
 217
 218 private:
 219
 220   DISABLE_COPY_AND_ASSIGN (btrace_data);
 221
 222   void fini ();
 223 };
 224
 225 /* Target specific branch trace information.  */
 226 struct btrace_target_info
 227 {
 228   btrace_target_info (ptid_t ptid) : ptid (ptid)
 229     {}
 230
 231   btrace_target_info (ptid_t ptid, btrace_config conf)
 232     : ptid (ptid), conf (conf)
 233     {}
 234
 235   virtual ~btrace_target_info () = default;
 236
 237   /* The ptid of this thread.  */
 238   ptid_t ptid {};
 239
 240   /* The obtained branch trace configuration.  */
 241   btrace_config conf {};
 242 };
 243
 244 /* Enumeration of btrace read types.  */
 245
 246 enum btrace_read_type
 247 {
 248   /* Send all available trace.  */
 249   BTRACE_READ_ALL,
 250
 251   /* Send all available trace, if it changed.  */
 252   BTRACE_READ_NEW,
 253
 254   /* Send the trace since the last request.  This will fail if the trace
 255      buffer overflowed.  */
 256   BTRACE_READ_DELTA
 257 };
 258
 259 /* Enumeration of btrace errors.  */
 260
 261 enum btrace_error
 262 {
 263   /* No error.  Everything is OK.  */
 264   BTRACE_ERR_NONE,
 265
 266   /* An unknown error.  */
 267   BTRACE_ERR_UNKNOWN,
 268
 269   /* Branch tracing is not supported on this system.  */
 270   BTRACE_ERR_NOT_SUPPORTED,
 271
 272   /* The branch trace buffer overflowed; no delta read possible.  */
 273   BTRACE_ERR_OVERFLOW
 274 };
 275
 276 /* Return a string representation of FORMAT.  */
 277 extern const char *btrace_format_string (enum btrace_format format);
 278
 279 /* Return an abbreviation string representation of FORMAT.  */
 280 extern const char *btrace_format_short_string (enum btrace_format format);
 281
 282 /* Append the branch trace data from SRC to the end of DST.
 283    Both SRC and DST must use the same format.
 284    Returns zero on success; a negative number otherwise.  */
 285 extern int btrace_data_append (struct btrace_data *dst,
 286                                const struct btrace_data *src);
 287
 288 #endif /* COMMON_BTRACE_COMMON_H */