gdb/probe.h

   1 /* Generic SDT probe support for GDB.
   2
   3    Copyright (C) 2012 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 struct linespec_result;
  26
  27 /* Structure useful for passing the header names in the method
  28    `gen_ui_out_table_header'.  */
  29
  30 struct info_probe_column
  31   {
  32     /* The internal name of the field.  This string cannot be capitalized nor
  33        localized, e.g., "extra_field".  */
  34
  35     const char *field_name;
  36
  37     /* The field name to be printed in the `info probes' command.  This
  38        string can be capitalized and localized, e.g., _("Extra Field").  */
  39     const char *print_name;
  40   };
  41
  42 typedef struct info_probe_column info_probe_column_s;
  43 DEF_VEC_O (info_probe_column_s);
  44
  45 /* Operations associated with a probe.  */
  46
  47 struct probe_ops
  48   {
  49     /* Method responsible for verifying if LINESPECP is a valid linespec for
  50        a probe breakpoint.  It should return 1 if it is, or zero if it is not.
  51        It also should update LINESPECP in order to discard the breakpoint
  52        option associated with this linespec.  For example, if the option is
  53        `-probe', and the LINESPECP is `-probe abc', the function should
  54        return 1 and set LINESPECP to `abc'.  */
  55
  56     int (*is_linespec) (const char **linespecp);
  57
  58     /* Function that should fill PROBES with known probes from OBJFILE.  */
  59
  60     void (*get_probes) (VEC (probe_p) **probes, struct objfile *objfile);
  61
  62     /* Function used to relocate addresses from PROBE according to some DELTA
  63        provided.  */
  64
  65     void (*relocate) (struct probe *probe, CORE_ADDR delta);
  66
  67     /* Return the number of arguments of PROBE.  */
  68
  69     unsigned (*get_probe_argument_count) (struct probe *probe);
  70
  71     /* Evaluate the Nth argument from the PROBE, returning a value
  72        corresponding to it.  The argument number is represented N.  */
  73
  74     struct value *(*evaluate_probe_argument) (struct probe *probe,
  75                                               unsigned n);
  76
  77     /* Compile the Nth argument of the PROBE to an agent expression.
  78        The argument number is represented by N.  */
  79
  80     void (*compile_to_ax) (struct probe *probe, struct agent_expr *aexpr,
  81                            struct axs_value *axs_value, unsigned n);
  82
  83     /* Set the semaphore associated with the PROBE.  This function only makes
  84        sense if the probe has a concept of semaphore associated to a
  85        probe.  */
  86
  87     void (*set_semaphore) (struct probe *probe, struct gdbarch *gdbarch);
  88
  89     /* Clear the semaphore associated with the PROBE.  This function only
  90        makes sense if the probe has a concept of semaphore associated to
  91        a probe.  */
  92
  93     void (*clear_semaphore) (struct probe *probe, struct gdbarch *gdbarch);
  94
  95     /* Function called to destroy PROBE's specific data.  This function
  96        shall not free PROBE itself.  */
  97
  98     void (*destroy) (struct probe *probe);
  99
 100     /* Function responsible for providing the extra fields that will be
 101        printed in the `info probes' command.  It should fill HEADS
 102        with whatever extra fields it needs.  If the backend doesn't need
 103        to print extra fields, it can set this method to NULL.  */
 104
 105     void (*gen_info_probes_table_header) (VEC (info_probe_column_s) **heads);
 106
 107     /* Function that will fill VALUES with the values of the extra fields
 108        to be printed for PROBE.  If the backend implements the
 109        `gen_ui_out_table_header' method, then it should implement
 110        this method as well.  The backend should also guarantee that the
 111        order and the number of values in the vector is exactly the same
 112        as the order of the extra fields provided in the method
 113        `gen_ui_out_table_header'.  If a certain field is to be skipped
 114        when printing the information, you can push a NULL value in that
 115        position in the vector.  */
 116
 117     void (*gen_info_probes_table_values) (struct probe *probe,
 118                                           VEC (const_char_ptr) **values);
 119   };
 120
 121 /* Definition of a vector of probe_ops.  */
 122
 123 typedef const struct probe_ops *probe_ops_cp;
 124 DEF_VEC_P (probe_ops_cp);
 125 extern VEC (probe_ops_cp) *all_probe_ops;
 126
 127 /* The probe_ops associated with the generic probe.  */
 128
 129 extern const struct probe_ops probe_ops_any;
 130
 131 /* Helper function that, given KEYWORDS, iterate over it trying to match
 132    each keyword with LINESPECP.  If it succeeds, it updates the LINESPECP
 133    pointer and returns 1.  Otherwise, nothing is done to LINESPECP and zero
 134    is returned.  */
 135
 136 extern int probe_is_linespec_by_keyword (const char **linespecp,
 137                                          const char *const *keywords);
 138
 139 /* Return specific PROBE_OPS * matching *LINESPECP and possibly updating
 140    *LINESPECP to skip its "-probe-type " prefix.  Return &probe_ops_any if
 141    *LINESPECP matches "-probe ", that is any unspecific probe.  Return NULL if
 142    *LINESPECP is not identified as any known probe type, *LINESPECP is not
 143    modified in such case.  */
 144
 145 extern const struct probe_ops *probe_linespec_to_ops (const char **linespecp);
 146
 147 /* The probe itself.  The struct contains generic information about the
 148    probe, and then some specific information which should be stored in
 149    the `probe_info' field.  */
 150
 151 struct probe
 152   {
 153     /* The operations associated with this probe.  */
 154     const struct probe_ops *pops;
 155
 156     /* The objfile which contains this probe.  Even if the probe is also
 157        present in a separate debug objfile, this variable always points to
 158        the non-separate debug objfile.  */
 159     struct objfile *objfile;
 160
 161     /* The name of the probe.  */
 162     const char *name;
 163
 164     /* The provider of the probe.  It generally defaults to the name of
 165        the objfile which contains the probe.  */
 166     const char *provider;
 167
 168     /* The address where the probe is inserted.  */
 169     CORE_ADDR address;
 170   };
 171
 172 /* A helper for linespec that decodes a probe specification.  It returns a
 173    symtabs_and_lines object and updates *ARGPTR or throws an error.  The
 174    argument PTYPE specifies the type of the probe(s) to be parsed.  */
 175
 176 extern struct symtabs_and_lines parse_probes (char **argptr,
 177                                               struct linespec_result *canon);
 178
 179 /* Helper function to register the proper probe_ops to a newly created probe.
 180    This function is mainly called from `sym_get_probes'.  */
 181
 182 extern void register_probe_ops (struct probe *probe);
 183
 184 /* Given a PC, find an associated probe with type PTYPE.  If a probe is
 185    found, return it.  If no probe is found, return NULL.  */
 186
 187 extern struct probe *find_probe_by_pc (CORE_ADDR pc);
 188
 189 /* Search OBJFILE for a probe with the given PROVIDER, NAME and PTYPE.
 190    Return a VEC of all probes that were found.  If no matching probe
 191    is found, return NULL.  The caller must free the VEC.  */
 192
 193 extern VEC (probe_p) *find_probes_in_objfile (struct objfile *objfile,
 194                                               const char *provider,
 195                                               const char *name);
 196
 197 /* Generate a `info probes' command output for probe_ops represented by
 198    POPS.  If POPS is NULL it considers any probes types.  It is a helper
 199    function that can be used by the probe backends to print their
 200    `info probe TYPE'.  */
 201
 202 extern void info_probes_for_ops (char *arg, int from_tty,
 203                                  const struct probe_ops *pops);
 204
 205 /* Return the `cmd_list_element' associated with the `info probes' command,
 206    or create a new one if it doesn't exist.  Helper function that serves the
 207    purpose of avoiding the case of a backend using the `cmd_list_element'
 208    associated with `info probes', without having it registered yet.  */
 209
 210 extern struct cmd_list_element **info_probes_cmdlist_get (void);
 211
 212 /* A convenience function that finds a probe at the PC in FRAME and
 213    evaluates argument N, with 0 <= N < number_of_args.  If there is no
 214    probe at that location, or if the probe does not have enough arguments,
 215    this returns NULL.  */
 216
 217 extern struct value *probe_safe_evaluate_at_pc (struct frame_info *frame,
 218                                                 unsigned n);
 219
 220 #endif /* !defined (PROBE_H) */