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