gdb/probe.h

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