GDB (xrefs)

/tmp/gdb-8.1/gdb/probe.h
Go to the documentation of this file.
1 /* Generic SDT probe support for GDB.
2
3 Copyright (C) 2012-2018 Free Software Foundation, Inc.
4
5 This file is part of GDB.
6
7 This program is free software; you can redistribute it and/or modify
8 it under the terms of the GNU General Public License as published by
9 the Free Software Foundation; either version 3 of the License, or
10 (at your option) any later version.
11
12 This program is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 GNU General Public License for more details.
16
17 You should have received a copy of the GNU General Public License
18 along with this program. If not, see <http://www.gnu.org/licenses/>. */
19
20 #if !defined (PROBE_H)
21 #define PROBE_H 1
22
23 struct event_location;
24 struct linespec_result;
25
26 /* Structure useful for passing the header names in the method
27 `gen_ui_out_table_header'. */
28
29 struct info_probe_column
30 {
31 /* The internal name of the field. This string cannot be capitalized nor
32 localized, e.g., "extra_field". */
33 const char *field_name;
34
35 /* The field name to be printed in the `info probes' command. This
36 string can be capitalized and localized, e.g., _("Extra Field"). */
37 const char *print_name;
38 };
39
40 /* Operations that act on probes, but are specific to each backend.
41 These methods do not go into the 'class probe' because they do not
42 act on a single probe; instead, they are used to operate on many
43 probes at once, or to provide information about the probe backend
44 itself, instead of a single probe.
45
46 Each probe backend needs to inherit this class and implement all of
47 the virtual functions specified here. Then, an object shall be
48 instantiated and added (or "registered") to the
49 ALL_STATIC_PROBE_OPS vector so that the frontend probe interface
50 can use it in the generic probe functions. */
51
52 class static_probe_ops
53 {
54 public:
55 /* Method responsible for verifying if LINESPECP is a valid linespec
56 for a probe breakpoint. It should return true if it is, or false
57 if it is not. It also should update LINESPECP in order to
58 discard the breakpoint option associated with this linespec. For
59 example, if the option is `-probe', and the LINESPECP is `-probe
60 abc', the function should return 1 and set LINESPECP to
61 `abc'. */
62 virtual bool is_linespec (const char **linespecp) const = 0;
63
64 /* Function that should fill PROBES with known probes from OBJFILE. */
65 virtual void get_probes (std::vector<probe *> *probes,
66 struct objfile *objfile) const = 0;
67
68 /* Return a pointer to a name identifying the probe type. This is
69 the string that will be displayed in the "Type" column of the
70 `info probes' command. */
71 virtual const char *type_name () const = 0;
72
73 /* Return true if the probe can be enabled; false otherwise. */
74 virtual bool can_enable () const
75 {
76 return false;
77 }
78
79 /* Function responsible for providing the extra fields that will be
80 printed in the `info probes' command. It should fill HEADS
81 with whatever extra fields it needs. If no extra fields are
82 required by the probe backend, the method EMIT_INFO_PROBES_FIELDS
83 should return false. */
84 virtual std::vector<struct info_probe_column>
85 gen_info_probes_table_header () const = 0;
86 };
87
88 /* Definition of a vector of static_probe_ops. */
89
90 extern std::vector<const static_probe_ops *> all_static_probe_ops;
91
92 /* Helper function that, given KEYWORDS, iterate over it trying to match
93 each keyword with LINESPECP. If it succeeds, it updates the LINESPECP
94 pointer and returns 1. Otherwise, nothing is done to LINESPECP and zero
95 is returned. */
96
97 extern int probe_is_linespec_by_keyword (const char **linespecp,
98 const char *const *keywords);
99
100 /* Return specific STATIC_PROBE_OPS * matching *LINESPECP and possibly
101 updating LINESPECP to skip its "-probe-type " prefix. Return
102 &static_probe_ops_any if LINESPECP matches "-probe ", that is any
103 unspecific probe. Return NULL if LINESPECP is not identified as
104 any known probe type, *LINESPECP is not modified in such case. */
105
106 extern const static_probe_ops *
107 probe_linespec_to_static_ops (const char **linespecp);
108
109 /* The probe itself. The class contains generic information about the
110 probe. */
111
112 class probe
113 {
114 public:
115 /* Default constructor for a probe. */
116 probe (std::string &&name_, std::string &&provider_, CORE_ADDR address_,
117 struct gdbarch *arch_)
118 : m_name (std::move (name_)), m_provider (std::move (provider_)),
119 m_address (address_), m_arch (arch_)
120 {}
121
122 /* Virtual destructor. */
123 virtual ~probe ()
124 {}
125
126 /* Compute the probe's relocated address. OBJFILE is the objfile
127 in which the probe originated. */
128 virtual CORE_ADDR get_relocated_address (struct objfile *objfile) = 0;
129
130 /* Return the number of arguments of the probe. This function can
131 throw an exception. */
132 virtual unsigned get_argument_count (struct frame_info *frame) = 0;
133
134 /* Return 1 if the probe interface can evaluate the arguments of
135 probe, zero otherwise. See the comments on
136 sym_probe_fns:can_evaluate_probe_arguments for more
137 details. */
138 virtual bool can_evaluate_arguments () const = 0;
139
140 /* Evaluate the Nth argument from the probe, returning a value
141 corresponding to it. The argument number is represented N.
142 This function can throw an exception. */
143 virtual struct value *evaluate_argument (unsigned n,
144 struct frame_info *frame) = 0;
145
146 /* Compile the Nth argument of the probe to an agent expression.
147 The argument number is represented by N. */
148 virtual void compile_to_ax (struct agent_expr *aexpr,
149 struct axs_value *axs_value,
150 unsigned n) = 0;
151
152 /* Set the semaphore associated with the probe. This function only
153 makes sense if the probe has a concept of semaphore associated to
154 a probe. */
155 virtual void set_semaphore (struct objfile *objfile,
156 struct gdbarch *gdbarch)
157 {}
158
159 /* Clear the semaphore associated with the probe. This function
160 only makes sense if the probe has a concept of semaphore
161 associated to a probe. */
162 virtual void clear_semaphore (struct objfile *objfile,
163 struct gdbarch *gdbarch)
164 {}
165
166 /* Return the pointer to the static_probe_ops instance related to
167 the probe type. */
168 virtual const static_probe_ops *get_static_ops () const = 0;
169
170 /* Function that will fill VALUES with the values of the extra
171 fields to be printed for the probe.
172
173 If the backend implements the `gen_ui_out_table_header' method,
174 then it should implement this method as well. The backend should
175 also guarantee that the order and the number of values in the
176 vector is exactly the same as the order of the extra fields
177 provided in the method `gen_ui_out_table_header'. If a certain
178 field is to be skipped when printing the information, you can
179 push a NULL value in that position in the vector. */
180 virtual std::vector<const char *> gen_info_probes_table_values () const
181 {
182 return std::vector<const char *> ();
183 }
184
185 /* Enable the probe. The semantics of "enabling" a probe depend on
186 the specific backend. This function can throw an exception. */
187 virtual void enable ()
188 {}
189
190 /* Disable the probe. The semantics of "disabling" a probe depend
191 on the specific backend. This function can throw an
192 exception. */
193 virtual void disable ()
194 {}
195
196 /* Getter for M_NAME. */
197 const std::string &get_name () const
198 {
199 return m_name;
200 }
201
202 /* Getter for M_PROVIDER. */
203 const std::string &get_provider () const
204 {
205 return m_provider;
206 }
207
208 /* Getter for M_ADDRESS. */
209 CORE_ADDR get_address () const
210 {
211 return m_address;
212 }
213
214 /* Getter for M_ARCH. */
215 struct gdbarch *get_gdbarch () const
216 {
217 return m_arch;
218 }
219
220 private:
221 /* The name of the probe. */
222 std::string m_name;
223
224 /* The provider of the probe. It generally defaults to the name of
225 the objfile which contains the probe. */
226 std::string m_provider;
227
228 /* The address where the probe is inserted, relative to
229 SECT_OFF_TEXT. */
230 CORE_ADDR m_address;
231
232 /* The probe's architecture. */
233 struct gdbarch *m_arch;
234 };
235
236 /* A bound probe holds a pointer to a probe and a pointer to the
237 probe's defining objfile. This is needed because probes are
238 independent of the program space and thus require relocation at
239 their point of use. */
240
241 struct bound_probe
242 {
243 /* Create an empty bound_probe object. */
244 bound_probe ()
245 {}
246
247 /* Create and initialize a bound_probe object using PROBE and OBJFILE. */
248 bound_probe (probe *probe_, struct objfile *objfile_)
249 : prob (probe_), objfile (objfile_)
250 {}
251
252 /* The probe. */
253 probe *prob = NULL;
254
255 /* The objfile in which the probe originated. */
256 struct objfile *objfile = NULL;
257 };
258
259 /* A helper for linespec that decodes a probe specification. It
260 returns a std::vector<symtab_and_line> object and updates LOC or
261 throws an error. */
262
263 extern std::vector<symtab_and_line> parse_probes
264 (const struct event_location *loc,
265 struct program_space *pspace,
266 struct linespec_result *canon);
267
268 /* Given a PC, find an associated probe. If a probe is found, return
269 it. If no probe is found, return a bound probe whose fields are
270 both NULL. */
271
272 extern struct bound_probe find_probe_by_pc (CORE_ADDR pc);
273
274 /* Search OBJFILE for a probe with the given PROVIDER, NAME. Return a
275 VEC of all probes that were found. If no matching probe is found,
276 return an empty vector. */
277
278 extern std::vector<probe *> find_probes_in_objfile (struct objfile *objfile,
279 const char *provider,
280 const char *name);
281
282 /* Generate a `info probes' command output for probes associated with
283 SPOPS. If SPOPS is related to the "any probe" type, then all probe
284 types are considered. It is a helper function that can be used by
285 the probe backends to print their `info probe TYPE'. */
286
287 extern void info_probes_for_spops (const char *arg, int from_tty,
288 const static_probe_ops *spops);
289
290 /* Return the `cmd_list_element' associated with the `info probes' command,
291 or create a new one if it doesn't exist. Helper function that serves the
292 purpose of avoiding the case of a backend using the `cmd_list_element'
293 associated with `info probes', without having it registered yet. */
294
295 extern struct cmd_list_element **info_probes_cmdlist_get (void);
296
297 /* A convenience function that finds a probe at the PC in FRAME and
298 evaluates argument N, with 0 <= N < number_of_args. If there is no
299 probe at that location, or if the probe does not have enough arguments,
300 this returns NULL. */
301
302 extern struct value *probe_safe_evaluate_at_pc (struct frame_info *frame,
303 unsigned n);
304
305 #endif /* !defined (PROBE_H) */
gdbarch
Definition: gdbarch.c:127
string
const char * string
Definition: signals.c:50
probe
Definition: probe.h:112
axs_value
Definition: ax-gdb.h:77
bound_probe::prob
probe * prob
Definition: probe.h:253
extract_bp_kind::loc
probe::set_semaphore
virtual void set_semaphore(struct objfile *objfile, struct gdbarch *gdbarch)
Definition: probe.h:155
probe::enable
virtual void enable()
Definition: probe.h:187
probe::evaluate_argument
virtual struct value * evaluate_argument(unsigned n, struct frame_info *frame)=0
CORE_ADDR
bfd_vma CORE_ADDR
Definition: common-types.h:41
cmd_list_element
Definition: cli-decode.h:46
probe_is_linespec_by_keyword
int probe_is_linespec_by_keyword(const char **linespecp, const char *const *keywords)
Definition: probe.c:724
objfile::pspace
struct program_space * pspace
Definition: objfiles.h:315
static_probe_ops::gen_info_probes_table_header
virtual std::vector< struct info_probe_column > gen_info_probes_table_header() const =0
agent_expr
Definition: ax.h:83
frame_info
Definition: frame.c:85
probe::get_address
CORE_ADDR get_address() const
Definition: probe.h:209
info_probes_cmdlist_get
struct cmd_list_element ** info_probes_cmdlist_get(void)
Definition: probe.c:782
probe::clear_semaphore
virtual void clear_semaphore(struct objfile *objfile, struct gdbarch *gdbarch)
Definition: probe.h:162
info_probe_column
Definition: probe.h:29
probe::~probe
virtual ~probe()
Definition: probe.h:123
static_probe_ops::get_probes
virtual void get_probes(std::vector< probe *> *probes, struct objfile *objfile) const =0
probe::get_provider
const std::string & get_provider() const
Definition: probe.h:203
probe::m_arch
struct gdbarch * m_arch
Definition: probe.h:233
name
const char *const name
Definition: aarch64-tdep.c:76
parse_probes
std::vector< symtab_and_line > parse_probes(const struct event_location *loc, struct program_space *pspace, struct linespec_result *canon)
Definition: probe.c:119
bound_probe::bound_probe
bound_probe(probe *probe_, struct objfile *objfile_)
Definition: probe.h:248
all_static_probe_ops
std::vector< const static_probe_ops * > all_static_probe_ops
Definition: probe.c:882
probe::probe
probe(std::string &&name_, std::string &&provider_, CORE_ADDR address_, struct gdbarch *arch_)
Definition: probe.h:116
probe::m_address
CORE_ADDR m_address
Definition: probe.h:230
probe::get_name
const std::string & get_name() const
Definition: probe.h:197
probe::m_name
std::string m_name
Definition: probe.h:222
probe_safe_evaluate_at_pc
struct value * probe_safe_evaluate_at_pc(struct frame_info *frame, unsigned n)
Definition: probe.c:693
info_probe_column::field_name
const char * field_name
Definition: probe.h:33
probe_linespec_to_static_ops
const static_probe_ops * probe_linespec_to_static_ops(const char **linespecp)
Definition: probe.c:712
event_location
Definition: location.c:36
probe::gen_info_probes_table_values
virtual std::vector< const char * > gen_info_probes_table_values() const
Definition: probe.h:180
info_probe_column::print_name
const char * print_name
Definition: probe.h:37
static_probe_ops
Definition: probe.h:52
probe::get_relocated_address
virtual CORE_ADDR get_relocated_address(struct objfile *objfile)=0
probe::get_argument_count
virtual unsigned get_argument_count(struct frame_info *frame)=0
bound_probe
Definition: probe.h:241
value
Definition: value.c:169
objfile
Definition: objfiles.h:286
info_probes_for_spops
void info_probes_for_spops(const char *arg, int from_tty, const static_probe_ops *spops)
Definition: probe.c:489
static_probe_ops::can_enable
virtual bool can_enable() const
Definition: probe.h:74
linespec_result
Definition: linespec.h:56
probe::compile_to_ax
virtual void compile_to_ax(struct agent_expr *aexpr, struct axs_value *axs_value, unsigned n)=0
bound_probe::bound_probe
bound_probe()
Definition: probe.h:244
static_probe_ops::type_name
virtual const char * type_name() const =0
static_probe_ops::is_linespec
virtual bool is_linespec(const char **linespecp) const =0
find_probe_by_pc
struct bound_probe find_probe_by_pc(CORE_ADDR pc)
Definition: probe.c:247
probe::m_provider
std::string m_provider
Definition: probe.h:226
probe::disable
virtual void disable()
Definition: probe.h:193
probe::can_evaluate_arguments
virtual bool can_evaluate_arguments() const =0
probe::get_static_ops
virtual const static_probe_ops * get_static_ops() const =0
program_space
Definition: progspace.h:137
probe::get_gdbarch
struct gdbarch * get_gdbarch() const
Definition: probe.h:215
find_probes_in_objfile
std::vector< probe * > find_probes_in_objfile(struct objfile *objfile, const char *provider, const char *name)
Definition: probe.c:220