gdb/extension-priv.h

   1 /* Private implementation details of interface between gdb and its
   2    extension languages.
   3
   4    Copyright (C) 2014-2019 Free Software Foundation, Inc.
   5
   6    This file is part of GDB.
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 3 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  20
  21 #ifndef EXTENSION_PRIV_H
  22 #define EXTENSION_PRIV_H
  23
  24 #include <signal.h>
  25
  26 /* Local non-gdb includes.  */
  27 #include "cli/cli-script.h"
  28 #include "extension.h"
  29
  30 /* High level description of an extension/scripting language.
  31    An entry for each is compiled into GDB regardless of whether the support
  32    is present.  This is done so that we can issue meaningful errors if the
  33    support is not compiled in.  */
  34
  35 struct extension_language_defn
  36 {
  37   /* Enum of the extension language.  */
  38   enum extension_language language;
  39
  40   /* The name of the extension language, lowercase.  E.g., python.  */
  41   const char *name;
  42
  43   /* The capitalized name of the extension language.
  44      For python this is "Python".  For gdb this is "GDB".  */
  45   const char *capitalized_name;
  46
  47   /* The file suffix of this extension language.  E.g., ".py".  */
  48   const char *suffix;
  49
  50   /* The suffix of per-objfile scripts to auto-load.
  51      E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py.  */
  52   const char *auto_load_suffix;
  53
  54   /* We support embedding external extension language code in GDB's own
  55      scripting language.  We do this by having a special command that begins
  56      the extension language snippet, and terminate it with "end".
  57      This specifies the control type used to implement this.  */
  58   enum command_control_type cli_control_type;
  59
  60   /* A pointer to the "methods" to load scripts in this language,
  61      or NULL if the support is not compiled into GDB.  */
  62   const struct extension_language_script_ops *script_ops;
  63
  64   /* Either a pointer to the "methods" of the extension language interface
  65      or NULL if the support is not compiled into GDB.
  66      This is also NULL for GDB's own scripting language which is relatively
  67      primitive, and doesn't provide these features.  */
  68   const struct extension_language_ops *ops;
  69 };
  70
  71 /* The interface for loading scripts from external extension languages,
  72    as well as GDB's own scripting language.
  73    All of these methods are required to be implemented.
  74
  75    By convention all of these functions take a pseudo-this parameter
  76    as the first argument.  */
  77
  78 struct extension_language_script_ops
  79 {
  80   /* Load a script.  This is called, e.g., via the "source" command.
  81      If there's an error while processing the script this function may,
  82      but is not required to, throw an error.  */
  83   script_sourcer_func *script_sourcer;
  84
  85   /* Load a script attached to an objfile.
  86      If there's an error while processing the script this function may,
  87      but is not required to, throw an error.  */
  88   objfile_script_sourcer_func *objfile_script_sourcer;
  89
  90   /* Execute a script attached to an objfile.
  91      If there's an error while processing the script this function may,
  92      but is not required to, throw an error.  */
  93   objfile_script_executor_func *objfile_script_executor;
  94
  95   /* Return non-zero if auto-loading scripts in this extension language
  96      is enabled.  */
  97   int (*auto_load_enabled) (const struct extension_language_defn *);
  98 };
  99
 100 /* The interface for making calls from GDB to an external extension
 101    language.  This is for non-script-loading related functionality, like
 102    pretty-printing, etc.  The reason these are separated out is GDB's own
 103    scripting language makes use of extension_language_script_opts, but it
 104    makes no use of these.  There is no (current) intention to split
 105    extension_language_ops up any further.
 106    All of these methods are optional and may be NULL, except where
 107    otherwise indicated.
 108
 109    By convention all of these functions take a pseudo-this parameter
 110    as the first argument.  */
 111
 112 struct extension_language_ops
 113 {
 114   /* Called at the end of gdb initialization to give the extension language
 115      an opportunity to finish up.  This is useful for things like adding
 116      new commands where one has to wait until gdb itself is initialized.  */
 117   void (*finish_initialization) (const struct extension_language_defn *);
 118
 119   /* Return non-zero if the extension language successfully initialized.
 120      This method is required.  */
 121   int (*initialized) (const struct extension_language_defn *);
 122
 123   /* Process a sequence of commands embedded in GDB's own scripting language.
 124      E.g.,
 125      python
 126      print 42
 127      end  */
 128   void (*eval_from_control_command) (const struct extension_language_defn *,
 129                                      struct command_line *);
 130
 131   /* Type-printing support:
 132      start_type_printers, apply_type_printers, free_type_printers.
 133      These methods are optional and may be NULL, but if one of them is
 134      implemented then they all must be.  */
 135
 136   /* Called before printing a type.  */
 137   void (*start_type_printers) (const struct extension_language_defn *,
 138                                struct ext_lang_type_printers *);
 139
 140   /* Try to pretty-print TYPE.  If successful the pretty-printed type is
 141      stored in *PRETTIED_TYPE, and the caller must free it.
 142      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
 143      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
 144      This function has a bit of a funny name, since it actually applies
 145      recognizers, but this seemed clearer given the start_type_printers
 146      and free_type_printers functions.  */
 147   enum ext_lang_rc (*apply_type_printers)
 148     (const struct extension_language_defn *,
 149      const struct ext_lang_type_printers *,
 150      struct type *, char **prettied_type);
 151
 152   /* Called after a type has been printed to give the type pretty-printer
 153      mechanism an opportunity to clean up.  */
 154   void (*free_type_printers) (const struct extension_language_defn *,
 155                               struct ext_lang_type_printers *);
 156
 157   /* Try to pretty-print a value of type TYPE located at VAL's contents
 158      buffer + EMBEDDED_OFFSET, which came from the inferior at address
 159      ADDRESS + EMBEDDED_OFFSET, onto stdio stream STREAM according to
 160      OPTIONS.
 161      VAL is the whole object that came from ADDRESS.
 162      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
 163      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.  */
 164   enum ext_lang_rc (*apply_val_pretty_printer)
 165     (const struct extension_language_defn *,
 166      struct type *type,
 167      LONGEST embedded_offset, CORE_ADDR address,
 168      struct ui_file *stream, int recurse,
 169      struct value *val, const struct value_print_options *options,
 170      const struct language_defn *language);
 171
 172   /* GDB access to the "frame filter" feature.
 173      FRAME is the source frame to start frame-filter invocation.  FLAGS is an
 174      integer holding the flags for printing.  The following elements of
 175      the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
 176      PRINT_LEVEL is a flag indicating whether to print the frame's
 177      relative level in the output.  PRINT_FRAME_INFO is a flag that
 178      indicates whether this function should print the frame
 179      information, PRINT_ARGS is a flag that indicates whether to print
 180      frame arguments, and PRINT_LOCALS, likewise, with frame local
 181      variables.  ARGS_TYPE is an enumerator describing the argument
 182      format, OUT is the output stream to print.  FRAME_LOW is the
 183      beginning of the slice of frames to print, and FRAME_HIGH is the
 184      upper limit of the frames to count.  Returns SCR_BT_ERROR on error,
 185      or SCR_BT_COMPLETED on success.  */
 186   enum ext_lang_bt_status (*apply_frame_filter)
 187     (const struct extension_language_defn *,
 188      struct frame_info *frame, frame_filter_flags flags,
 189      enum ext_lang_frame_args args_type,
 190      struct ui_out *out, int frame_low, int frame_high);
 191
 192   /* Update values held by the extension language when OBJFILE is discarded.
 193      New global types must be created for every such value, which must then be
 194      updated to use the new types.
 195      This function typically just iterates over all appropriate values and
 196      calls preserve_one_value for each one.
 197      COPIED_TYPES is used to prevent cycles / duplicates and is passed to
 198      preserve_one_value.  */
 199   void (*preserve_values) (const struct extension_language_defn *,
 200                            struct objfile *objfile, htab_t copied_types);
 201
 202   /* Return non-zero if there is a stop condition for the breakpoint.
 203      This is used to implement the restriction that a breakpoint may have
 204      at most one condition.  */
 205   int (*breakpoint_has_cond) (const struct extension_language_defn *,
 206                               struct breakpoint *);
 207
 208   /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
 209      condition for the breakpoint, and if so whether the program should
 210      stop.  This is called when the program has stopped at the specified
 211      breakpoint.
 212      While breakpoints can have at most one condition, this is called for
 213      every extension language, even if another extension language has a
 214      "stop" method: other kinds of breakpoints may be implemented using
 215      this method, e.g., "finish breakpoints" in Python.  */
 216   enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
 217     (const struct extension_language_defn *, struct breakpoint *);
 218
 219   /* The next two are used to connect GDB's SIGINT handling with the
 220      extension language's.
 221
 222      Terminology: If an extension language can use GDB's SIGINT handling then
 223      we say the extension language has "cooperative SIGINT handling".
 224      Python is an example of this.
 225
 226      These need not be implemented, but if one of them is implemented
 227      then they all must be.  */
 228
 229   /* Set the SIGINT indicator.
 230      This is called by GDB's SIGINT handler and must be async-safe.  */
 231   void (*set_quit_flag) (const struct extension_language_defn *);
 232
 233   /* Return non-zero if a SIGINT has occurred.
 234      This is expected to also clear the indicator.  */
 235   int (*check_quit_flag) (const struct extension_language_defn *);
 236
 237   /* Called before gdb prints its prompt, giving extension languages an
 238      opportunity to change it with set_prompt.
 239      Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
 240      the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
 241      encountered.
 242      Extension languages are called in order, and once the prompt is
 243      changed or an error occurs no further languages are called.  */
 244   enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
 245                                      const char *current_gdb_prompt);
 246
 247   /* Return a vector of matching xmethod workers defined in this
 248      extension language.  The workers service methods with name
 249      METHOD_NAME on objects of type OBJ_TYPE.  The vector is returned
 250      in DM_VEC.
 251
 252      This field may be NULL if the extension language does not support
 253      xmethods.  */
 254   enum ext_lang_rc (*get_matching_xmethod_workers)
 255     (const struct extension_language_defn *extlang,
 256      struct type *obj_type,
 257      const char *method_name,
 258      std::vector<xmethod_worker_up> *dm_vec);
 259 };
 260
 261 /* State necessary to restore a signal handler to its previous value.  */
 262
 263 struct signal_handler
 264 {
 265   /* Non-zero if "handler" has been set.  */
 266   int handler_saved;
 267
 268   /* The signal handler.  */
 269   sighandler_t handler;
 270 };
 271
 272 /* State necessary to restore the currently active extension language
 273    to its previous value.  */
 274
 275 struct active_ext_lang_state
 276 {
 277   /* The previously active extension language.  */
 278   const struct extension_language_defn *ext_lang;
 279
 280   /* Its SIGINT handler.  */
 281   struct signal_handler sigint_handler;
 282 };
 283
 284 extern const struct extension_language_defn *get_active_ext_lang (void);
 285
 286 extern struct active_ext_lang_state *set_active_ext_lang
 287   (const struct extension_language_defn *);
 288
 289 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
 290
 291 #endif /* EXTENSION_PRIV_H */