gdb/extension-priv.h

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