gdb/extension-priv.h

   1 /* Private implementation details of interface between gdb and its
   2    extension languages.
   3
   4    Copyright (C) 2014-2017 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 "extension.h"
  25 #include <signal.h>
  26 #include "cli/cli-script.h"
  27
  28 /* The return code for some API calls.  */
  29
  30 enum ext_lang_rc
  31   {
  32     /* The operation completed successfully.  */
  33     EXT_LANG_RC_OK,
  34
  35     /* The operation was not performed (e.g., no pretty-printer).  */
  36     EXT_LANG_RC_NOP,
  37
  38     /* There was an error (e.g., Python error while printing a value).
  39        When an error occurs no further extension languages are tried.
  40        This is to preserve existing behaviour, and because it's convenient
  41        for Python developers.
  42        Note: This is different than encountering a memory error trying to read
  43        a value for pretty-printing.  Here we're referring to, e.g., programming
  44        errors that trigger an exception in the extension language.  */
  45     EXT_LANG_RC_ERROR
  46   };
  47
  48 /* High level description of an extension/scripting language.
  49    An entry for each is compiled into GDB regardless of whether the support
  50    is present.  This is done so that we can issue meaningful errors if the
  51    support is not compiled in.  */
  52
  53 struct extension_language_defn
  54 {
  55   /* Enum of the extension language.  */
  56   enum extension_language language;
  57
  58   /* The name of the extension language, lowercase.  E.g., python.  */
  59   const char *name;
  60
  61   /* The capitalized name of the extension language.
  62      For python this is "Python".  For gdb this is "GDB".  */
  63   const char *capitalized_name;
  64
  65   /* The file suffix of this extension language.  E.g., ".py".  */
  66   const char *suffix;
  67
  68   /* The suffix of per-objfile scripts to auto-load.
  69      E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py.  */
  70   const char *auto_load_suffix;
  71
  72   /* We support embedding external extension language code in GDB's own
  73      scripting language.  We do this by having a special command that begins
  74      the extension language snippet, and terminate it with "end".
  75      This specifies the control type used to implement this.  */
  76   enum command_control_type cli_control_type;
  77
  78   /* A pointer to the "methods" to load scripts in this language,
  79      or NULL if the support is not compiled into GDB.  */
  80   const struct extension_language_script_ops *script_ops;
  81
  82   /* Either a pointer to the "methods" of the extension language interface
  83      or NULL if the support is not compiled into GDB.
  84      This is also NULL for GDB's own scripting language which is relatively
  85      primitive, and doesn't provide these features.  */
  86   const struct extension_language_ops *ops;
  87 };
  88
  89 /* The interface for loading scripts from external extension languages,
  90    as well as GDB's own scripting language.
  91    All of these methods are required to be implemented.
  92
  93    By convention all of these functions take a pseudo-this parameter
  94    as the first argument.  */
  95
  96 struct extension_language_script_ops
  97 {
  98   /* Load a script.  This is called, e.g., via the "source" command.
  99      If there's an error while processing the script this function may,
 100      but is not required to, throw an error.  */
 101   script_sourcer_func *script_sourcer;
 102
 103   /* Load a script attached to an objfile.
 104      If there's an error while processing the script this function may,
 105      but is not required to, throw an error.  */
 106   objfile_script_sourcer_func *objfile_script_sourcer;
 107
 108   /* Execute a script attached to an objfile.
 109      If there's an error while processing the script this function may,
 110      but is not required to, throw an error.  */
 111   objfile_script_executor_func *objfile_script_executor;
 112
 113   /* Return non-zero if auto-loading scripts in this extension language
 114      is enabled.  */
 115   int (*auto_load_enabled) (const struct extension_language_defn *);
 116 };
 117
 118 /* The interface for making calls from GDB to an external extension
 119    language.  This is for non-script-loading related functionality, like
 120    pretty-printing, etc.  The reason these are separated out is GDB's own
 121    scripting language makes use of extension_language_script_opts, but it
 122    makes no use of these.  There is no (current) intention to split
 123    extension_language_ops up any further.
 124    All of these methods are optional and may be NULL, except where
 125    otherwise indicated.
 126
 127    By convention all of these functions take a pseudo-this parameter
 128    as the first argument.  */
 129
 130 struct extension_language_ops
 131 {
 132   /* Called at the end of gdb initialization to give the extension language
 133      an opportunity to finish up.  This is useful for things like adding
 134      new commands where one has to wait until gdb itself is initialized.  */
 135   void (*finish_initialization) (const struct extension_language_defn *);
 136
 137   /* Return non-zero if the extension language successfully initialized.
 138      This method is required.  */
 139   int (*initialized) (const struct extension_language_defn *);
 140
 141   /* Process a sequence of commands embedded in GDB's own scripting language.
 142      E.g.,
 143      python
 144      print 42
 145      end  */
 146   void (*eval_from_control_command) (const struct extension_language_defn *,
 147                                      struct command_line *);
 148
 149   /* Type-printing support:
 150      start_type_printers, apply_type_printers, free_type_printers.
 151      These methods are optional and may be NULL, but if one of them is
 152      implemented then they all must be.  */
 153
 154   /* Called before printing a type.  */
 155   void (*start_type_printers) (const struct extension_language_defn *,
 156                                struct ext_lang_type_printers *);
 157
 158   /* Try to pretty-print TYPE.  If successful the pretty-printed type is
 159      stored in *PRETTIED_TYPE, and the caller must free it.
 160      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
 161      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
 162      This function has a bit of a funny name, since it actually applies
 163      recognizers, but this seemed clearer given the start_type_printers
 164      and free_type_printers functions.  */
 165   enum ext_lang_rc (*apply_type_printers)
 166     (const struct extension_language_defn *,
 167      const struct ext_lang_type_printers *,
 168      struct type *, char **prettied_type);
 169
 170   /* Called after a type has been printed to give the type pretty-printer
 171      mechanism an opportunity to clean up.  */
 172   void (*free_type_printers) (const struct extension_language_defn *,
 173                               struct ext_lang_type_printers *);
 174
 175   /* Try to pretty-print a value of type TYPE located at VAL's contents
 176      buffer + EMBEDDED_OFFSET, which came from the inferior at address
 177      ADDRESS + EMBEDDED_OFFSET, onto stdio stream STREAM according to
 178      OPTIONS.
 179      VAL is the whole object that came from ADDRESS.
 180      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
 181      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.  */
 182   enum ext_lang_rc (*apply_val_pretty_printer)
 183     (const struct extension_language_defn *,
 184      struct type *type,
 185      LONGEST embedded_offset, CORE_ADDR address,
 186      struct ui_file *stream, int recurse,
 187      struct value *val, const struct value_print_options *options,
 188      const struct language_defn *language);
 189
 190   /* GDB access to the "frame filter" feature.
 191      FRAME is the source frame to start frame-filter invocation.  FLAGS is an
 192      integer holding the flags for printing.  The following elements of
 193      the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
 194      PRINT_LEVEL is a flag indicating whether to print the frame's
 195      relative level in the output.  PRINT_FRAME_INFO is a flag that
 196      indicates whether this function should print the frame
 197      information, PRINT_ARGS is a flag that indicates whether to print
 198      frame arguments, and PRINT_LOCALS, likewise, with frame local
 199      variables.  ARGS_TYPE is an enumerator describing the argument
 200      format, OUT is the output stream to print.  FRAME_LOW is the
 201      beginning of the slice of frames to print, and FRAME_HIGH is the
 202      upper limit of the frames to count.  Returns SCR_BT_ERROR on error,
 203      or SCR_BT_COMPLETED on success.  */
 204   enum ext_lang_bt_status (*apply_frame_filter)
 205     (const struct extension_language_defn *,
 206      struct frame_info *frame, int flags, enum ext_lang_frame_args args_type,
 207      struct ui_out *out, int frame_low, int frame_high);
 208
 209   /* Update values held by the extension language when OBJFILE is discarded.
 210      New global types must be created for every such value, which must then be
 211      updated to use the new types.
 212      This function typically just iterates over all appropriate values and
 213      calls preserve_one_value for each one.
 214      COPIED_TYPES is used to prevent cycles / duplicates and is passed to
 215      preserve_one_value.  */
 216   void (*preserve_values) (const struct extension_language_defn *,
 217                            struct objfile *objfile, htab_t copied_types);
 218
 219   /* Return non-zero if there is a stop condition for the breakpoint.
 220      This is used to implement the restriction that a breakpoint may have
 221      at most one condition.  */
 222   int (*breakpoint_has_cond) (const struct extension_language_defn *,
 223                               struct breakpoint *);
 224
 225   /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
 226      condition for the breakpoint, and if so whether the program should
 227      stop.  This is called when the program has stopped at the specified
 228      breakpoint.
 229      While breakpoints can have at most one condition, this is called for
 230      every extension language, even if another extension language has a
 231      "stop" method: other kinds of breakpoints may be implemented using
 232      this method, e.g., "finish breakpoints" in Python.  */
 233   enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
 234     (const struct extension_language_defn *, struct breakpoint *);
 235
 236   /* The next two are used to connect GDB's SIGINT handling with the
 237      extension language's.
 238
 239      Terminology: If an extension language can use GDB's SIGINT handling then
 240      we say the extension language has "cooperative SIGINT handling".
 241      Python is an example of this.
 242
 243      These need not be implemented, but if one of them is implemented
 244      then they all must be.  */
 245
 246   /* Set the SIGINT indicator.
 247      This is called by GDB's SIGINT handler and must be async-safe.  */
 248   void (*set_quit_flag) (const struct extension_language_defn *);
 249
 250   /* Return non-zero if a SIGINT has occurred.
 251      This is expected to also clear the indicator.  */
 252   int (*check_quit_flag) (const struct extension_language_defn *);
 253
 254   /* Called before gdb prints its prompt, giving extension languages an
 255      opportunity to change it with set_prompt.
 256      Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
 257      the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
 258      encountered.
 259      Extension languages are called in order, and once the prompt is
 260      changed or an error occurs no further languages are called.  */
 261   enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
 262                                      const char *current_gdb_prompt);
 263
 264   /* xmethod support:
 265      clone_xmethod_worker_data, free_xmethod_worker_data,
 266      get_matching_xmethod_workers, get_xmethod_arg_types,
 267      get_xmethod_return_type, invoke_xmethod.
 268      These methods are optional and may be NULL, but if one of them is
 269      implemented then they all must be.  */
 270
 271   /* Clone DATA and return a new but identical xmethod worker data
 272      object for this extension language.  */
 273   void * (*clone_xmethod_worker_data)
 274     (const struct extension_language_defn *extlang, void *data);
 275
 276   /* Free the DATA object of this extension language.  */
 277   void (*free_xmethod_worker_data)
 278     (const struct extension_language_defn *extlang, void *data);
 279
 280   /* Return a vector of matching xmethod workers defined in this
 281      extension language.  The workers service methods with name
 282      METHOD_NAME on objects of type OBJ_TYPE.  The vector is returned
 283      in DM_VEC.  */
 284   enum ext_lang_rc (*get_matching_xmethod_workers)
 285     (const struct extension_language_defn *extlang,
 286      struct type *obj_type,
 287      const char *method_name,
 288      xmethod_worker_vec **dm_vec);
 289
 290   /* Given a WORKER servicing a particular method, return the types
 291      of the arguments the method takes.  The number of arguments is
 292      returned in NARGS, and their types are returned in the array
 293      ARGTYPES.  */
 294   enum ext_lang_rc (*get_xmethod_arg_types)
 295     (const struct extension_language_defn *extlang,
 296      struct xmethod_worker *worker,
 297      int *nargs,
 298      struct type ***arg_types);
 299
 300   /* Given a WORKER servicing a particular method, fetch the type of the
 301      result of the method.  OBJECT, ARGS, NARGS are the same as for
 302      invoke_xmethod.  The result type is stored in *RESULT_TYPE.
 303      For backward compatibility with 7.9, which did not support getting the
 304      result type, if the get_result_type operation is not provided by WORKER
 305      then EXT_LANG_RC_OK is returned and NULL is returned in *RESULT_TYPE.  */
 306   enum ext_lang_rc (*get_xmethod_result_type)
 307     (const struct extension_language_defn *extlang,
 308      struct xmethod_worker *worker,
 309      struct value *object, struct value **args, int nargs,
 310      struct type **result_type);
 311
 312   /* Invoke the xmethod serviced by WORKER.  The xmethod is invoked
 313      on OBJECT with arguments in the array ARGS.  NARGS is the length of
 314      this array.  Returns the value returned by the xmethod.  */
 315   struct value * (*invoke_xmethod)
 316     (const struct extension_language_defn *extlang,
 317      struct xmethod_worker *worker,
 318      struct value *object,
 319      struct value **args,
 320      int nargs);
 321 };
 322
 323 /* State necessary to restore a signal handler to its previous value.  */
 324
 325 struct signal_handler
 326 {
 327   /* Non-zero if "handler" has been set.  */
 328   int handler_saved;
 329
 330   /* The signal handler.  */
 331   sighandler_t handler;
 332 };
 333
 334 /* State necessary to restore the currently active extension language
 335    to its previous value.  */
 336
 337 struct active_ext_lang_state
 338 {
 339   /* The previously active extension language.  */
 340   const struct extension_language_defn *ext_lang;
 341
 342   /* Its SIGINT handler.  */
 343   struct signal_handler sigint_handler;
 344 };
 345
 346 extern const struct extension_language_defn *get_active_ext_lang (void);
 347
 348 extern struct active_ext_lang_state *set_active_ext_lang
 349   (const struct extension_language_defn *);
 350
 351 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
 352
 353 #endif /* EXTENSION_PRIV_H */