gdb/probe.h

   1 /* Generic SDT probe support for GDB.
   2
   3    Copyright (C) 2012-2014 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     /* Function used to relocate addresses from PROBE according to some DELTA
  68        provided.  */
  69
  70     void (*relocate) (struct probe *probe, CORE_ADDR delta);
  71
  72     /* Return the number of arguments of PROBE.  */
  73
  74     unsigned (*get_probe_argument_count) (struct probe *probe,
  75                                           struct frame_info *frame);
  76
  77     /* Return 1 if the probe interface can evaluate the arguments of probe
  78        PROBE, zero otherwise.  See the comments on
  79        sym_probe_fns:can_evaluate_probe_arguments for more details.  */
  80
  81     int (*can_evaluate_probe_arguments) (struct probe *probe);
  82
  83     /* Evaluate the Nth argument from the PROBE, returning a value
  84        corresponding to it.  The argument number is represented N.  */
  85
  86     struct value *(*evaluate_probe_argument) (struct probe *probe,
  87                                               unsigned n,
  88                                               struct frame_info *frame);
  89
  90     /* Compile the Nth argument of the PROBE to an agent expression.
  91        The argument number is represented by N.  */
  92
  93     void (*compile_to_ax) (struct probe *probe, struct agent_expr *aexpr,
  94                            struct axs_value *axs_value, unsigned n);
  95
  96     /* Set the semaphore associated with the PROBE.  This function only makes
  97        sense if the probe has a concept of semaphore associated to a
  98        probe.  */
  99
 100     void (*set_semaphore) (struct probe *probe, struct gdbarch *gdbarch);
 101
 102     /* Clear the semaphore associated with the PROBE.  This function only
 103        makes sense if the probe has a concept of semaphore associated to
 104        a probe.  */
 105
 106     void (*clear_semaphore) (struct probe *probe, struct gdbarch *gdbarch);
 107
 108     /* Function called to destroy PROBE's specific data.  This function
 109        shall not free PROBE itself.  */
 110
 111     void (*destroy) (struct probe *probe);
 112
 113     /* Function responsible for providing the extra fields that will be
 114        printed in the `info probes' command.  It should fill HEADS
 115        with whatever extra fields it needs.  If the backend doesn't need
 116        to print extra fields, it can set this method to NULL.  */
 117
 118     void (*gen_info_probes_table_header) (VEC (info_probe_column_s) **heads);
 119
 120     /* Function that will fill VALUES with the values of the extra fields
 121        to be printed for PROBE.  If the backend implements the
 122        `gen_ui_out_table_header' method, then it should implement
 123        this method as well.  The backend should also guarantee that the
 124        order and the number of values in the vector is exactly the same
 125        as the order of the extra fields provided in the method
 126        `gen_ui_out_table_header'.  If a certain field is to be skipped
 127        when printing the information, you can push a NULL value in that
 128        position in the vector.  */
 129
 130     void (*gen_info_probes_table_values) (struct probe *probe,
 131                                           VEC (const_char_ptr) **values);
 132   };
 133
 134 /* Definition of a vector of probe_ops.  */
 135
 136 typedef const struct probe_ops *probe_ops_cp;
 137 DEF_VEC_P (probe_ops_cp);
 138 extern VEC (probe_ops_cp) *all_probe_ops;
 139
 140 /* The probe_ops associated with the generic probe.  */
 141
 142 extern const struct probe_ops probe_ops_any;
 143
 144 /* Helper function that, given KEYWORDS, iterate over it trying to match
 145    each keyword with LINESPECP.  If it succeeds, it updates the LINESPECP
 146    pointer and returns 1.  Otherwise, nothing is done to LINESPECP and zero
 147    is returned.  */
 148
 149 extern int probe_is_linespec_by_keyword (const char **linespecp,
 150                                          const char *const *keywords);
 151
 152 /* Return specific PROBE_OPS * matching *LINESPECP and possibly updating
 153    *LINESPECP to skip its "-probe-type " prefix.  Return &probe_ops_any if
 154    *LINESPECP matches "-probe ", that is any unspecific probe.  Return NULL if
 155    *LINESPECP is not identified as any known probe type, *LINESPECP is not
 156    modified in such case.  */
 157
 158 extern const struct probe_ops *probe_linespec_to_ops (const char **linespecp);
 159
 160 /* The probe itself.  The struct contains generic information about the
 161    probe, and then some specific information which should be stored in
 162    the `probe_info' field.  */
 163
 164 struct probe
 165   {
 166     /* The operations associated with this probe.  */
 167     const struct probe_ops *pops;
 168
 169     /* The objfile which contains this probe.  Even if the probe is also
 170        present in a separate debug objfile, this variable always points to
 171        the non-separate debug objfile.  */
 172     struct objfile *objfile;
 173
 174     /* The name of the probe.  */
 175     const char *name;
 176
 177     /* The provider of the probe.  It generally defaults to the name of
 178        the objfile which contains the probe.  */
 179     const char *provider;
 180
 181     /* The address where the probe is inserted.  */
 182     CORE_ADDR address;
 183   };
 184
 185 /* A helper for linespec that decodes a probe specification.  It returns a
 186    symtabs_and_lines object and updates *ARGPTR or throws an error.  The
 187    argument PTYPE specifies the type of the probe(s) to be parsed.  */
 188
 189 extern struct symtabs_and_lines parse_probes (char **argptr,
 190                                               struct linespec_result *canon);
 191
 192 /* Helper function to register the proper probe_ops to a newly created probe.
 193    This function is mainly called from `sym_get_probes'.  */
 194
 195 extern void register_probe_ops (struct probe *probe);
 196
 197 /* Given a PC, find an associated probe with type PTYPE.  If a probe is
 198    found, return it.  If no probe is found, return NULL.  */
 199
 200 extern struct probe *find_probe_by_pc (CORE_ADDR pc);
 201
 202 /* Search OBJFILE for a probe with the given PROVIDER, NAME and PTYPE.
 203    Return a VEC of all probes that were found.  If no matching probe
 204    is found, return NULL.  The caller must free the VEC.  */
 205
 206 extern VEC (probe_p) *find_probes_in_objfile (struct objfile *objfile,
 207                                               const char *provider,
 208                                               const char *name);
 209
 210 /* Generate a `info probes' command output for probe_ops represented by
 211    POPS.  If POPS is NULL it considers any probes types.  It is a helper
 212    function that can be used by the probe backends to print their
 213    `info probe TYPE'.  */
 214
 215 extern void info_probes_for_ops (char *arg, int from_tty,
 216                                  const struct probe_ops *pops);
 217
 218 /* Return the `cmd_list_element' associated with the `info probes' command,
 219    or create a new one if it doesn't exist.  Helper function that serves the
 220    purpose of avoiding the case of a backend using the `cmd_list_element'
 221    associated with `info probes', without having it registered yet.  */
 222
 223 extern struct cmd_list_element **info_probes_cmdlist_get (void);
 224
 225 /* Return the argument count of the specified probe.  */
 226
 227 extern unsigned get_probe_argument_count (struct probe *probe,
 228                                           struct frame_info *frame);
 229
 230 /* Return 1 if the probe interface associated with PROBE can evaluate
 231    arguments, zero otherwise.  See the comments on the definition of
 232    sym_probe_fns:can_evaluate_probe_arguments for more details.  */
 233
 234 extern int can_evaluate_probe_arguments (struct probe *probe);
 235
 236 /* Evaluate argument N of the specified probe.  N must be between 0
 237    inclusive and get_probe_argument_count exclusive.  */
 238
 239 extern struct value *evaluate_probe_argument (struct probe *probe,
 240                                               unsigned n,
 241                                               struct frame_info *frame);
 242
 243 /* A convenience function that finds a probe at the PC in FRAME and
 244    evaluates argument N, with 0 <= N < number_of_args.  If there is no
 245    probe at that location, or if the probe does not have enough arguments,
 246    this returns NULL.  */
 247
 248 extern struct value *probe_safe_evaluate_at_pc (struct frame_info *frame,
 249                                                 unsigned n);
 250
 251 #endif /* !defined (PROBE_H) */