gdb/probe.h

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