contrib/gdb-7/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 #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
  35 struct info_probe_column
  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
  47 typedef struct info_probe_column info_probe_column_s;
  48 DEF_VEC_O (info_probe_column_s);
  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
  70     CORE_ADDR (*get_probe_address) (struct probe *probe,
  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
 127     void (*gen_info_probes_table_header) (VEC (info_probe_column_s) **heads);
 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.  */
 202     CORE_ADDR address;
 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
 210 struct bound_probe
 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) */