gdb/probe.h

   1 /* Generic SDT probe support for GDB.
   2
   3    Copyright (C) 2012-2019 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 struct linespec_result;
  25
  26 /* Structure useful for passing the header names in the method
  27    `gen_ui_out_table_header'.  */
  28
  29 struct info_probe_column
  30   {
  31     /* The internal name of the field.  This string cannot be capitalized nor
  32        localized, e.g., "extra_field".  */
  33     const char *field_name;
  34
  35     /* The field name to be printed in the `info probes' command.  This
  36        string can be capitalized and localized, e.g., _("Extra Field").  */
  37     const char *print_name;
  38   };
  39
  40 /* Operations that act on probes, but are specific to each backend.
  41    These methods do not go into the 'class probe' because they do not
  42    act on a single probe; instead, they are used to operate on many
  43    probes at once, or to provide information about the probe backend
  44    itself, instead of a single probe.
  45
  46    Each probe backend needs to inherit this class and implement all of
  47    the virtual functions specified here.  Then, an object shall be
  48    instantiated and added (or "registered") to the
  49    ALL_STATIC_PROBE_OPS vector so that the frontend probe interface
  50    can use it in the generic probe functions.  */
  51
  52 class static_probe_ops
  53 {
  54 public:
  55   /* Method responsible for verifying if LINESPECP is a valid linespec
  56      for a probe breakpoint.  It should return true if it is, or false
  57      if it is not.  It also should update LINESPECP in order to
  58      discard the breakpoint option associated with this linespec.  For
  59      example, if the option is `-probe', and the LINESPECP is `-probe
  60      abc', the function should return 1 and set LINESPECP to
  61      `abc'.  */
  62   virtual bool is_linespec (const char **linespecp) const = 0;
  63
  64   /* Function that should fill PROBES with known probes from OBJFILE.  */
  65   virtual void get_probes (std::vector<std::unique_ptr<probe>> *probes,
  66                             struct objfile *objfile) const = 0;
  67
  68   /* Return a pointer to a name identifying the probe type.  This is
  69      the string that will be displayed in the "Type" column of the
  70      `info probes' command.  */
  71   virtual const char *type_name () const = 0;
  72
  73   /* Return true if the probe can be enabled; false otherwise.  */
  74   virtual bool can_enable () const
  75   {
  76     return false;
  77   }
  78
  79   /* Function responsible for providing the extra fields that will be
  80      printed in the `info probes' command.  It should fill HEADS
  81      with whatever extra fields it needs.  If no extra fields are
  82      required by the probe backend, the method EMIT_INFO_PROBES_FIELDS
  83      should return false.  */
  84   virtual std::vector<struct info_probe_column>
  85     gen_info_probes_table_header () const = 0;
  86 };
  87
  88 /* Definition of a vector of static_probe_ops.  */
  89
  90 extern std::vector<const static_probe_ops *> all_static_probe_ops;
  91
  92 /* Helper function that, given KEYWORDS, iterate over it trying to match
  93    each keyword with LINESPECP.  If it succeeds, it updates the LINESPECP
  94    pointer and returns 1.  Otherwise, nothing is done to LINESPECP and zero
  95    is returned.  */
  96
  97 extern int probe_is_linespec_by_keyword (const char **linespecp,
  98                                          const char *const *keywords);
  99
 100 /* Return specific STATIC_PROBE_OPS * matching *LINESPECP and possibly
 101    updating LINESPECP to skip its "-probe-type " prefix.  Return
 102    &static_probe_ops_any if LINESPECP matches "-probe ", that is any
 103    unspecific probe.  Return NULL if LINESPECP is not identified as
 104    any known probe type, *LINESPECP is not modified in such case.  */
 105
 106 extern const static_probe_ops *
 107   probe_linespec_to_static_ops (const char **linespecp);
 108
 109 /* The probe itself.  The class contains generic information about the
 110    probe.  */
 111
 112 class probe
 113 {
 114 public:
 115   /* Default constructor for a probe.  */
 116   probe (std::string &&name_, std::string &&provider_, CORE_ADDR address_,
 117          struct gdbarch *arch_)
 118     : m_name (std::move (name_)), m_provider (std::move (provider_)),
 119       m_address (address_), m_arch (arch_)
 120   {}
 121
 122   /* Virtual destructor.  */
 123   virtual ~probe ()
 124   {}
 125
 126   /* Compute the probe's relocated address.  OBJFILE is the objfile
 127      in which the probe originated.  */
 128   virtual CORE_ADDR get_relocated_address (struct objfile *objfile) = 0;
 129
 130   /* Return the number of arguments of the probe.  This function can
 131      throw an exception.  */
 132   virtual unsigned get_argument_count (struct frame_info *frame) = 0;
 133
 134   /* Return 1 if the probe interface can evaluate the arguments of
 135      probe, zero otherwise.  See the comments on
 136      sym_probe_fns:can_evaluate_probe_arguments for more
 137      details.  */
 138   virtual bool can_evaluate_arguments () const = 0;
 139
 140   /* Evaluate the Nth argument from the probe, returning a value
 141      corresponding to it.  The argument number is represented N.
 142      This function can throw an exception.  */
 143   virtual struct value *evaluate_argument (unsigned n,
 144                                            struct frame_info *frame) = 0;
 145
 146   /* Compile the Nth argument of the probe to an agent expression.
 147      The argument number is represented by N.  */
 148   virtual void compile_to_ax (struct agent_expr *aexpr,
 149                               struct axs_value *axs_value,
 150                               unsigned n) = 0;
 151
 152   /* Set the semaphore associated with the probe.  This function only
 153      makes sense if the probe has a concept of semaphore associated to
 154      a probe.  */
 155   virtual void set_semaphore (struct objfile *objfile,
 156                               struct gdbarch *gdbarch)
 157   {}
 158
 159   /* Clear the semaphore associated with the probe.  This function
 160      only makes sense if the probe has a concept of semaphore
 161      associated to a probe.  */
 162   virtual void clear_semaphore (struct objfile *objfile,
 163                                 struct gdbarch *gdbarch)
 164   {}
 165
 166   /* Return the pointer to the static_probe_ops instance related to
 167      the probe type.  */
 168   virtual const static_probe_ops *get_static_ops () const = 0;
 169
 170   /* Function that will fill VALUES with the values of the extra
 171      fields to be printed for the probe.
 172
 173      If the backend implements the `gen_ui_out_table_header' method,
 174      then it should implement this method as well.  The backend should
 175      also guarantee that the order and the number of values in the
 176      vector is exactly the same as the order of the extra fields
 177      provided in the method `gen_ui_out_table_header'.  If a certain
 178      field is to be skipped when printing the information, you can
 179      push a NULL value in that position in the vector.  */
 180   virtual std::vector<const char *> gen_info_probes_table_values () const
 181   {
 182     return std::vector<const char *> ();
 183   }
 184
 185   /* Enable the probe.  The semantics of "enabling" a probe depend on
 186      the specific backend.  This function can throw an exception.  */
 187   virtual void enable ()
 188   {}
 189
 190   /* Disable the probe.  The semantics of "disabling" a probe depend
 191      on the specific backend.  This function can throw an
 192      exception.  */
 193   virtual void disable ()
 194   {}
 195
 196   /* Getter for M_NAME.  */
 197   const std::string &get_name () const
 198   {
 199     return m_name;
 200   }
 201
 202   /* Getter for M_PROVIDER.  */
 203   const std::string &get_provider () const
 204   {
 205     return m_provider;
 206   }
 207
 208   /* Getter for M_ADDRESS.  */
 209   CORE_ADDR get_address () const
 210   {
 211     return m_address;
 212   }
 213
 214   /* Getter for M_ARCH.  */
 215   struct gdbarch *get_gdbarch () const
 216   {
 217     return m_arch;
 218   }
 219
 220 private:
 221   /* The name of the probe.  */
 222   std::string m_name;
 223
 224   /* The provider of the probe.  It generally defaults to the name of
 225      the objfile which contains the probe.  */
 226   std::string m_provider;
 227
 228   /* The address where the probe is inserted, relative to
 229      SECT_OFF_TEXT.  */
 230   CORE_ADDR m_address;
 231
 232   /* The probe's architecture.  */
 233   struct gdbarch *m_arch;
 234 };
 235
 236 /* A bound probe holds a pointer to a probe and a pointer to the
 237    probe's defining objfile.  This is needed because probes are
 238    independent of the program space and thus require relocation at
 239    their point of use.  */
 240
 241 struct bound_probe
 242 {
 243   /* Create an empty bound_probe object.  */
 244   bound_probe ()
 245   {}
 246
 247   /* Create and initialize a bound_probe object using PROBE and OBJFILE.  */
 248   bound_probe (probe *probe_, struct objfile *objfile_)
 249   : prob (probe_), objfile (objfile_)
 250   {}
 251
 252   /* The probe.  */
 253   probe *prob = NULL;
 254
 255   /* The objfile in which the probe originated.  */
 256   struct objfile *objfile = NULL;
 257 };
 258
 259 /* A helper for linespec that decodes a probe specification.  It
 260    returns a std::vector<symtab_and_line> object and updates LOC or
 261    throws an error.  */
 262
 263 extern std::vector<symtab_and_line> parse_probes
 264   (const struct event_location *loc,
 265    struct program_space *pspace,
 266    struct linespec_result *canon);
 267
 268 /* Given a PC, find an associated probe.  If a probe is found, return
 269    it.  If no probe is found, return a bound probe whose fields are
 270    both NULL.  */
 271
 272 extern struct bound_probe find_probe_by_pc (CORE_ADDR pc);
 273
 274 /* Search OBJFILE for a probe with the given PROVIDER, NAME.  Return a
 275    VEC of all probes that were found.  If no matching probe is found,
 276    return an empty vector.  */
 277
 278 extern std::vector<probe *> find_probes_in_objfile (struct objfile *objfile,
 279                                                     const char *provider,
 280                                                     const char *name);
 281
 282 /* Generate a `info probes' command output for probes associated with
 283    SPOPS.  If SPOPS is related to the "any probe" type, then all probe
 284    types are considered.  It is a helper function that can be used by
 285    the probe backends to print their `info probe TYPE'.  */
 286
 287 extern void info_probes_for_spops (const char *arg, int from_tty,
 288                                    const static_probe_ops *spops);
 289
 290 /* Return the `cmd_list_element' associated with the `info probes' command,
 291    or create a new one if it doesn't exist.  Helper function that serves the
 292    purpose of avoiding the case of a backend using the `cmd_list_element'
 293    associated with `info probes', without having it registered yet.  */
 294
 295 extern struct cmd_list_element **info_probes_cmdlist_get (void);
 296
 297 /* A convenience function that finds a probe at the PC in FRAME and
 298    evaluates argument N, with 0 <= N < number_of_args.  If there is no
 299    probe at that location, or if the probe does not have enough arguments,
 300    this returns NULL.  */
 301
 302 extern struct value *probe_safe_evaluate_at_pc (struct frame_info *frame,
 303                                                 unsigned n);
 304
 305 #endif /* !defined (PROBE_H) */