gdb/extension-priv.h

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