GDB (xrefs)
/tmp/gdb-7.10/gdb/probe.h
Go to the documentation of this file.
1 /* Generic SDT probe support for GDB.
2 
3  Copyright (C) 2012-2015 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 "gdb_vecs.h"
24 
25 /* Definition of a vector of probes. */
26 
27 typedef struct probe *probe_p;
28 DEF_VEC_P (probe_p);
29 
30 struct linespec_result;
31 
32 /* Structure useful for passing the header names in the method
33  `gen_ui_out_table_header'. */
34 
36  {
37  /* The internal name of the field. This string cannot be capitalized nor
38  localized, e.g., "extra_field". */
39 
40  const char *field_name;
41 
42  /* The field name to be printed in the `info probes' command. This
43  string can be capitalized and localized, e.g., _("Extra Field"). */
44  const char *print_name;
45  };
46 
49 
50 /* Operations associated with a probe. */
51 
52 struct probe_ops
53  {
54  /* Method responsible for verifying if LINESPECP is a valid linespec for
55  a probe breakpoint. It should return 1 if it is, or zero if it is not.
56  It also should update LINESPECP in order to discard the breakpoint
57  option associated with this linespec. For example, if the option is
58  `-probe', and the LINESPECP is `-probe abc', the function should
59  return 1 and set LINESPECP to `abc'. */
60 
61  int (*is_linespec) (const char **linespecp);
62 
63  /* Function that should fill PROBES with known probes from OBJFILE. */
64 
65  void (*get_probes) (VEC (probe_p) **probes, struct objfile *objfile);
66 
67  /* Compute the probe's relocated address. OBJFILE is the objfile
68  in which the probe originated. */
69 
71  struct objfile *objfile);
72 
73  /* Return the number of arguments of PROBE. */
74 
75  unsigned (*get_probe_argument_count) (struct probe *probe,
76  struct frame_info *frame);
77 
78  /* Return 1 if the probe interface can evaluate the arguments of probe
79  PROBE, zero otherwise. See the comments on
80  sym_probe_fns:can_evaluate_probe_arguments for more details. */
81 
82  int (*can_evaluate_probe_arguments) (struct probe *probe);
83 
84  /* Evaluate the Nth argument from the PROBE, returning a value
85  corresponding to it. The argument number is represented N. */
86 
87  struct value *(*evaluate_probe_argument) (struct probe *probe,
88  unsigned n,
89  struct frame_info *frame);
90 
91  /* Compile the Nth argument of the PROBE to an agent expression.
92  The argument number is represented by N. */
93 
94  void (*compile_to_ax) (struct probe *probe, struct agent_expr *aexpr,
95  struct axs_value *axs_value, unsigned n);
96 
97  /* Set the semaphore associated with the PROBE. This function only makes
98  sense if the probe has a concept of semaphore associated to a
99  probe, otherwise it can be set to NULL. */
100 
101  void (*set_semaphore) (struct probe *probe, struct objfile *objfile,
102  struct gdbarch *gdbarch);
103 
104  /* Clear the semaphore associated with the PROBE. This function only
105  makes sense if the probe has a concept of semaphore associated to
106  a probe, otherwise it can be set to NULL. */
107 
108  void (*clear_semaphore) (struct probe *probe, struct objfile *objfile,
109  struct gdbarch *gdbarch);
110 
111  /* Function called to destroy PROBE's specific data. This function
112  shall not free PROBE itself. */
113 
114  void (*destroy) (struct probe *probe);
115 
116  /* Return a pointer to a name identifying the probe type. This is
117  the string that will be displayed in the "Type" column of the
118  `info probes' command. */
119 
120  const char *(*type_name) (struct probe *probe);
121 
122  /* Function responsible for providing the extra fields that will be
123  printed in the `info probes' command. It should fill HEADS
124  with whatever extra fields it needs. If the backend doesn't need
125  to print extra fields, it can set this method to NULL. */
126 
128 
129  /* Function that will fill VALUES with the values of the extra fields
130  to be printed for PROBE. If the backend implements the
131  `gen_ui_out_table_header' method, then it should implement
132  this method as well. The backend should also guarantee that the
133  order and the number of values in the vector is exactly the same
134  as the order of the extra fields provided in the method
135  `gen_ui_out_table_header'. If a certain field is to be skipped
136  when printing the information, you can push a NULL value in that
137  position in the vector. */
138 
139  void (*gen_info_probes_table_values) (struct probe *probe,
140  VEC (const_char_ptr) **values);
141 
142  /* Enable a probe. The semantics of "enabling" a probe depend on
143  the specific backend and the field can be NULL in case enabling
144  probes is not supported. */
145 
146  void (*enable_probe) (struct probe *probe);
147 
148  /* Disable a probe. The semantics of "disabling" a probe depend
149  on the specific backend and the field can be NULL in case
150  disabling probes is not supported. */
151 
152  void (*disable_probe) (struct probe *probe);
153  };
154 
155 /* Definition of a vector of probe_ops. */
156 
157 typedef const struct probe_ops *probe_ops_cp;
158 DEF_VEC_P (probe_ops_cp);
159 extern VEC (probe_ops_cp) *all_probe_ops;
160 
161 /* The probe_ops associated with the generic probe. */
162 
163 extern const struct probe_ops probe_ops_any;
164 
165 /* Helper function that, given KEYWORDS, iterate over it trying to match
166  each keyword with LINESPECP. If it succeeds, it updates the LINESPECP
167  pointer and returns 1. Otherwise, nothing is done to LINESPECP and zero
168  is returned. */
169 
170 extern int probe_is_linespec_by_keyword (const char **linespecp,
171  const char *const *keywords);
172 
173 /* Return specific PROBE_OPS * matching *LINESPECP and possibly updating
174  *LINESPECP to skip its "-probe-type " prefix. Return &probe_ops_any if
175  *LINESPECP matches "-probe ", that is any unspecific probe. Return NULL if
176  *LINESPECP is not identified as any known probe type, *LINESPECP is not
177  modified in such case. */
178 
179 extern const struct probe_ops *probe_linespec_to_ops (const char **linespecp);
180 
181 /* The probe itself. The struct contains generic information about the
182  probe, and then some specific information which should be stored in
183  the `probe_info' field. */
184 
185 struct probe
186  {
187  /* The operations associated with this probe. */
188  const struct probe_ops *pops;
189 
190  /* The probe's architecture. */
191  struct gdbarch *arch;
192 
193  /* The name of the probe. */
194  const char *name;
195 
196  /* The provider of the probe. It generally defaults to the name of
197  the objfile which contains the probe. */
198  const char *provider;
199 
200  /* The address where the probe is inserted, relative to
201  SECT_OFF_TEXT. */
203  };
204 
205 /* A bound probe holds a pointer to a probe and a pointer to the
206  probe's defining objfile. This is needed because probes are
207  independent of the program space and thus require relocation at
208  their point of use. */
209 
211  {
212  /* The probe. */
213 
214  struct probe *probe;
215 
216  /* The objfile in which the probe originated. */
217 
218  struct objfile *objfile;
219  };
220 
221 /* A helper for linespec that decodes a probe specification. It returns a
222  symtabs_and_lines object and updates *ARGPTR or throws an error. */
223 
224 extern struct symtabs_and_lines parse_probes (char **argptr,
225  struct linespec_result *canon);
226 
227 /* Helper function to register the proper probe_ops to a newly created probe.
228  This function is mainly called from `sym_get_probes'. */
229 
230 extern void register_probe_ops (struct probe *probe);
231 
232 /* Given a PC, find an associated probe. If a probe is found, return
233  it. If no probe is found, return a bound probe whose fields are
234  both NULL. */
235 
236 extern struct bound_probe find_probe_by_pc (CORE_ADDR pc);
237 
238 /* Search OBJFILE for a probe with the given PROVIDER, NAME. Return a
239  VEC of all probes that were found. If no matching probe is found,
240  return NULL. The caller must free the VEC. */
241 
242 extern VEC (probe_p) *find_probes_in_objfile (struct objfile *objfile,
243  const char *provider,
244  const char *name);
245 
246 /* Generate a `info probes' command output for probe_ops represented by
247  POPS. If POPS is NULL it considers any probes types. It is a helper
248  function that can be used by the probe backends to print their
249  `info probe TYPE'. */
250 
251 extern void info_probes_for_ops (const char *arg, int from_tty,
252  const struct probe_ops *pops);
253 
254 /* Return the `cmd_list_element' associated with the `info probes' command,
255  or create a new one if it doesn't exist. Helper function that serves the
256  purpose of avoiding the case of a backend using the `cmd_list_element'
257  associated with `info probes', without having it registered yet. */
258 
259 extern struct cmd_list_element **info_probes_cmdlist_get (void);
260 
261 /* Compute the probe's relocated address. OBJFILE is the objfile in
262  which the probe originated. */
263 
264 extern CORE_ADDR get_probe_address (struct probe *probe,
265  struct objfile *objfile);
266 
267 /* Return the argument count of the specified probe. */
268 
269 extern unsigned get_probe_argument_count (struct probe *probe,
270  struct frame_info *frame);
271 
272 /* Return 1 if the probe interface associated with PROBE can evaluate
273  arguments, zero otherwise. See the comments on the definition of
274  sym_probe_fns:can_evaluate_probe_arguments for more details. */
275 
276 extern int can_evaluate_probe_arguments (struct probe *probe);
277 
278 /* Evaluate argument N of the specified probe. N must be between 0
279  inclusive and get_probe_argument_count exclusive. */
280 
281 extern struct value *evaluate_probe_argument (struct probe *probe,
282  unsigned n,
283  struct frame_info *frame);
284 
285 /* A convenience function that finds a probe at the PC in FRAME and
286  evaluates argument N, with 0 <= N < number_of_args. If there is no
287  probe at that location, or if the probe does not have enough arguments,
288  this returns NULL. */
289 
290 extern struct value *probe_safe_evaluate_at_pc (struct frame_info *frame,
291  unsigned n);
292 
293 #endif /* !defined (PROBE_H) */
int(* can_evaluate_probe_arguments)(struct probe *probe)
Definition: probe.h:82
void(* enable_probe)(struct probe *probe)
Definition: probe.h:146
int(* is_linespec)(const char **linespecp)
Definition: probe.h:61
bfd_vma CORE_ADDR
Definition: common-types.h:41
int can_evaluate_probe_arguments(struct probe *probe)
Definition: probe.c:809
int probe_is_linespec_by_keyword(const char **linespecp, const char *const *keywords)
Definition: probe.c:860
DEF_VEC_P(probe_p)
void(* disable_probe)(struct probe *probe)
Definition: probe.h:152
void(* set_semaphore)(struct probe *probe, struct objfile *objfile, struct gdbarch *gdbarch)
Definition: probe.h:101
void(* get_probes)(VEC(probe_p)**probes, struct objfile *objfile)
Definition: probe.h:65
struct symtabs_and_lines parse_probes(char **argptr, struct linespec_result *canon)
Definition: probe.c:46
void(* gen_info_probes_table_values)(struct probe *probe, VEC(const_char_ptr)**values)
Definition: probe.h:139
const struct probe_ops * probe_linespec_to_ops(const char **linespecp)
Definition: probe.c:845
Definition: ax.h:95
unsigned get_probe_argument_count(struct probe *probe, struct frame_info *frame)
Definition: probe.c:801
struct cmd_list_element ** info_probes_cmdlist_get(void)
Definition: probe.c:909
const struct probe_ops * probe_ops_cp
Definition: probe.h:157
VEC(probe_ops_cp)*all_probe_ops
Definition: probe.c:1011
void(* compile_to_ax)(struct probe *probe, struct agent_expr *aexpr, struct axs_value *axs_value, unsigned n)
Definition: probe.h:94
unsigned(* get_probe_argument_count)(struct probe *probe, struct frame_info *frame)
Definition: probe.h:75
void register_probe_ops(struct probe *probe)
struct probe * probe_p
Definition: probe.h:27
const char * name
Definition: probe.h:194
void(* clear_semaphore)(struct probe *probe, struct objfile *objfile, struct gdbarch *gdbarch)
Definition: probe.h:108
struct objfile * objfile
Definition: probe.h:218
struct probe * probe
Definition: probe.h:214
CORE_ADDR address
Definition: probe.h:202
const char * const_char_ptr
Definition: gdb_vecs.h:26
struct value * probe_safe_evaluate_at_pc(struct frame_info *frame, unsigned n)
Definition: probe.c:826
const char const char * name
Definition: probe.h:243
const char * field_name
Definition: probe.h:40
const char * print_name
Definition: probe.h:44
void(* gen_info_probes_table_header)(VEC(info_probe_column_s)**heads)
Definition: probe.h:127
const char * provider
Definition: probe.h:198
Definition: probe.h:185
struct gdbarch * arch
Definition: probe.h:191
const char * provider
Definition: probe.h:243
Definition: value.c:172
CORE_ADDR(* get_probe_address)(struct probe *probe, struct objfile *objfile)
Definition: probe.h:70
const struct probe_ops probe_ops_any
Definition: probe.c:900
const char const char int
Definition: command.h:229
CORE_ADDR get_probe_address(struct probe *probe, struct objfile *objfile)
Definition: probe.c:793
void info_probes_for_ops(const char *arg, int from_tty, const struct probe_ops *pops)
Definition: probe.c:551
const struct probe_ops * pops
Definition: probe.h:188
struct value * evaluate_probe_argument(struct probe *probe, unsigned n, struct frame_info *frame)
Definition: probe.c:817
DEF_VEC_O(info_probe_column_s)
struct bound_probe find_probe_by_pc(CORE_ADDR pc)
Definition: probe.c:215
void(* destroy)(struct probe *probe)
Definition: probe.h:114