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