Automatic date update in version.in
[binutils-gdb.git] / gdbsupport / btrace-common.h
blob3c55ae92185b6bb597217c3dc0a6b10233a3aae6
1 /* Branch trace support for GDB, the GNU debugger.
3 Copyright (C) 2013-2022 Free Software Foundation, Inc.
5 Contributed by Intel Corp. <markus.t.metzger@intel.com>.
7 This file is part of GDB.
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.
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.
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/>. */
22 #ifndef COMMON_BTRACE_COMMON_H
23 #define COMMON_BTRACE_COMMON_H
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. */
29 /* A branch trace block.
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
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;
42 /* The address of the first byte of the last instruction in the block. */
43 CORE_ADDR end;
45 /* Simple constructor. */
46 btrace_block (CORE_ADDR begin, CORE_ADDR end)
47 : begin (begin),
48 end (end)
50 /* Nothing. */
54 /* Enumeration of btrace formats. */
56 enum btrace_format
58 /* No branch trace format. */
59 BTRACE_FORMAT_NONE,
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,
65 /* Branch trace is in Intel Processor Trace format. */
66 BTRACE_FORMAT_PT
69 /* An enumeration of cpu vendors. */
71 enum btrace_cpu_vendor
73 /* We do not know this vendor. */
74 CV_UNKNOWN,
76 /* Intel. */
77 CV_INTEL,
79 /* AMD. */
80 CV_AMD
83 /* A cpu identifier. */
85 struct btrace_cpu
87 /* The processor vendor. */
88 enum btrace_cpu_vendor vendor;
90 /* The cpu family. */
91 unsigned short family;
93 /* The cpu model. */
94 unsigned char model;
96 /* The cpu stepping. */
97 unsigned char stepping;
100 /* A BTS configuration. */
102 struct btrace_config_bts
104 /* The size of the branch trace buffer in bytes.
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;
111 /* An Intel Processor Trace configuration. */
113 struct btrace_config_pt
115 /* The size of the branch trace buffer in bytes.
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;
122 /* A branch tracing configuration.
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. */
129 struct btrace_config
131 /* The branch tracing format. */
132 enum btrace_format format;
134 /* The BTS format configuration. */
135 struct btrace_config_bts bts;
137 /* The Intel Processor Trace format configuration. */
138 struct btrace_config_pt pt;
141 /* Branch trace in BTS format. */
142 struct btrace_data_bts
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;
150 /* Configuration information to go with the trace data. */
151 struct btrace_data_pt_config
153 /* The processor on which the trace has been collected. */
154 struct btrace_cpu cpu;
157 /* Branch trace in Intel Processor Trace format. */
158 struct btrace_data_pt
160 /* Some configuration information to go with the data. */
161 struct btrace_data_pt_config config;
163 /* The trace data. */
164 gdb_byte *data;
166 /* The size of DATA in bytes. */
167 size_t size;
170 /* The branch trace data. */
171 struct btrace_data
173 btrace_data () = default;
175 ~btrace_data ()
177 fini ();
180 btrace_data &operator= (btrace_data &&other)
182 if (this != &other)
184 fini ();
185 format = other.format;
186 variant = other.variant;
187 other.format = BTRACE_FORMAT_NONE;
189 return *this;
192 /* Return true if this is empty; false otherwise. */
193 bool empty () const;
195 /* Clear this object. */
196 void clear ();
198 enum btrace_format format = BTRACE_FORMAT_NONE;
200 union
202 /* Format == BTRACE_FORMAT_BTS. */
203 struct btrace_data_bts bts;
205 /* Format == BTRACE_FORMAT_PT. */
206 struct btrace_data_pt pt;
207 } variant;
209 private:
211 DISABLE_COPY_AND_ASSIGN (btrace_data);
213 void fini ();
216 /* Target specific branch trace information. */
217 struct btrace_target_info;
219 /* Enumeration of btrace read types. */
221 enum btrace_read_type
223 /* Send all available trace. */
224 BTRACE_READ_ALL,
226 /* Send all available trace, if it changed. */
227 BTRACE_READ_NEW,
229 /* Send the trace since the last request. This will fail if the trace
230 buffer overflowed. */
231 BTRACE_READ_DELTA
234 /* Enumeration of btrace errors. */
236 enum btrace_error
238 /* No error. Everything is OK. */
239 BTRACE_ERR_NONE,
241 /* An unknown error. */
242 BTRACE_ERR_UNKNOWN,
244 /* Branch tracing is not supported on this system. */
245 BTRACE_ERR_NOT_SUPPORTED,
247 /* The branch trace buffer overflowed; no delta read possible. */
248 BTRACE_ERR_OVERFLOW
251 /* Return a string representation of FORMAT. */
252 extern const char *btrace_format_string (enum btrace_format format);
254 /* Return an abbreviation string representation of FORMAT. */
255 extern const char *btrace_format_short_string (enum btrace_format format);
257 /* Append the branch trace data from SRC to the end of DST.
258 Both SRC and DST must use the same format.
259 Returns zero on success; a negative number otherwise. */
260 extern int btrace_data_append (struct btrace_data *dst,
261 const struct btrace_data *src);
263 #endif /* COMMON_BTRACE_COMMON_H */