gdb/probe.h

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