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 122 /* A branch tracing configuration. 123 124 This describes the requested configuration as well as the actually 125 obtained configuration. 126 We describe the configuration for all different formats so we can 127 easily switch between formats. */ 128 129 struct btrace_config 130 { 131 /* The branch tracing format. */ 132 enum btrace_format format; 133 134 /* The BTS format configuration. */ 135 struct btrace_config_bts bts; 136 137 /* The Intel Processor Trace format configuration. */ 138 struct btrace_config_pt pt; 139 }; 140 141 /* Branch trace in BTS format. */ 142 struct btrace_data_bts 143 { 144 /* Branch trace is represented as a vector of branch trace blocks starting 145 with the most recent block. This needs to be a pointer as we place 146 btrace_data_bts into a union. */ 147 std::vector<btrace_block> *blocks; 148 }; 149 150 /* Configuration information to go with the trace data. */ 151 struct btrace_data_pt_config 152 { 153 /* The processor on which the trace has been collected. */ 154 struct btrace_cpu cpu; 155 }; 156 157 /* Branch trace in Intel Processor Trace format. */ 158 struct btrace_data_pt 159 { 160 /* Some configuration information to go with the data. */ 161 struct btrace_data_pt_config config; 162 163 /* The trace data. */ 164 gdb_byte *data; 165 166 /* The size of DATA in bytes. */ 167 size_t size; 168 }; 169 170 /* The branch trace data. */ 171 struct btrace_data 172 { 173 btrace_data () = default; 174 175 ~btrace_data () 176 { 177 fini (); 178 } 179 180 btrace_data &operator= (btrace_data &&other) 181 { 182 if (this != &other) 183 { 184 fini (); 185 format = other.format; 186 variant = other.variant; 187 other.format = BTRACE_FORMAT_NONE; 188 } 189 return *this; 190 } 191 192 /* Return true if this is empty; false otherwise. */ 193 bool empty () const; 194 195 /* Clear this object. */ 196 void clear (); 197 198 enum btrace_format format = BTRACE_FORMAT_NONE; 199 200 union 201 { 202 /* Format == BTRACE_FORMAT_BTS. */ 203 struct btrace_data_bts bts; 204 205 /* Format == BTRACE_FORMAT_PT. */ 206 struct btrace_data_pt pt; 207 } variant; 208 209 private: 210 211 DISABLE_COPY_AND_ASSIGN (btrace_data); 212 213 void fini (); 214 }; 215 216 /* Target specific branch trace information. */ 217 struct btrace_target_info 218 { 219 btrace_target_info (ptid_t ptid) : ptid (ptid) 220 {} 221 222 btrace_target_info (ptid_t ptid, btrace_config conf) 223 : ptid (ptid), conf (conf) 224 {} 225 226 virtual ~btrace_target_info () = default; 227 228 /* The ptid of this thread. */ 229 ptid_t ptid {}; 230 231 /* The obtained branch trace configuration. */ 232 btrace_config conf {}; 233 }; 234 235 /* Enumeration of btrace read types. */ 236 237 enum btrace_read_type 238 { 239 /* Send all available trace. */ 240 BTRACE_READ_ALL, 241 242 /* Send all available trace, if it changed. */ 243 BTRACE_READ_NEW, 244 245 /* Send the trace since the last request. This will fail if the trace 246 buffer overflowed. */ 247 BTRACE_READ_DELTA 248 }; 249 250 /* Enumeration of btrace errors. */ 251 252 enum btrace_error 253 { 254 /* No error. Everything is OK. */ 255 BTRACE_ERR_NONE, 256 257 /* An unknown error. */ 258 BTRACE_ERR_UNKNOWN, 259 260 /* Branch tracing is not supported on this system. */ 261 BTRACE_ERR_NOT_SUPPORTED, 262 263 /* The branch trace buffer overflowed; no delta read possible. */ 264 BTRACE_ERR_OVERFLOW 265 }; 266 267 /* Return a string representation of FORMAT. */ 268 extern const char *btrace_format_string (enum btrace_format format); 269 270 /* Return an abbreviation string representation of FORMAT. */ 271 extern const char *btrace_format_short_string (enum btrace_format format); 272 273 /* Append the branch trace data from SRC to the end of DST. 274 Both SRC and DST must use the same format. 275 Returns zero on success; a negative number otherwise. */ 276 extern int btrace_data_append (struct btrace_data *dst, 277 const struct btrace_data *src); 278 279 #endif /* COMMON_BTRACE_COMMON_H */ 280