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