gdb/extension-priv.h - gdb

Data types defined

Macros defined

Source code

  1. /* Private implementation details of interface between gdb and its
  2.    extension languages.

  4.    Copyright (C) 2014-2015 Free Software Foundation, Inc.

  6.    This file is part of GDB.

  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.

  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.

  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/>.  */

  21. #ifndef EXTENSION_PRIV_H
  22. ‌#define EXTENSION_PRIV_H

  24. #include "extension.h"

  26. /* The return code for some API calls.  */

  28. ‌enum ext_lang_rc
  29.   {
  30.     /* The operation completed successfully.  */
  31.     EXT_LANG_RC_OK,

  33.     /* The operation was not performed (e.g., no pretty-printer).  */
  34.     EXT_LANG_RC_NOP,

  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.   };

  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.  */

  51. ‌struct extension_language_defn
  52. {
  53.   /* Enum of the extension language.  */
  54.   enum extension_language language;

  56.   /* The name of the extension language, lowercase.  E.g., python.  */
  57.   const char *name;

  59.   /* The capitalized name of the extension language.
  60.      For python this is "Python".  For gdb this is "GDB".  */
  61.   const char *capitalized_name;

  63.   /* The file suffix of this extension language.  E.g., ".py".  */
  64.   const char *suffix;

  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;

  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;

  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;

  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. };

  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.

  91.    By convention all of these functions take a pseudo-this parameter
  92.    as the first argument.  */

  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;

  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;

  106.   /* Return non-zero if auto-loading scripts in this extension language
  107.      is enabled.  */
  108.   int (*auto_load_enabled) (const struct extension_language_defn *);
  109. };

  111. /* The interface for making calls from GDB to an external extension
  112.    language.  This is for non-script-loading related functionality, like
  113.    pretty-printing, etc.  The reason these are separated out is GDB's own
  114.    scripting language makes use of extension_language_script_opts, but it
  115.    makes no use of these.  There is no (current) intention to split
  116.    extension_language_ops up any further.
  117.    All of these methods are optional and may be NULL, except where
  118.    otherwise indicated.

  120.    By convention all of these functions take a pseudo-this parameter
  121.    as the first argument.  */

  123. ‌struct extension_language_ops
  124. {
  125.   /* Called at the end of gdb initialization to give the extension language
  126.      an opportunity to finish up.  This is useful for things like adding
  127.      new commands where one has to wait until gdb itself is initialized.  */
  128.   void (*finish_initialization) (const struct extension_language_defn *);

  130.   /* Return non-zero if the extension language successfully initialized.
  131.      This method is required.  */
  132.   int (*initialized) (const struct extension_language_defn *);

  134.   /* Process a sequence of commands embedded in GDB's own scripting language.
  135.      E.g.,
  136.      python
  137.      print 42
  138.      end  */
  139.   void (*eval_from_control_command) (const struct extension_language_defn *,
  140.                                      struct command_line *);

  142.   /* Type-printing support:
  143.      start_type_printers, apply_type_printers, free_type_printers.
  144.      These methods are optional and may be NULL, but if one of them is
  145.      implemented then they all must be.  */

  147.   /* Called before printing a type.  */
  148.   void (*start_type_printers) (const struct extension_language_defn *,
  149.                                struct ext_lang_type_printers *);

  151.   /* Try to pretty-print TYPE.  If successful the pretty-printed type is
  152.      stored in *PRETTIED_TYPE, and the caller must free it.
  153.      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
  154.      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
  155.      This function has a bit of a funny name, since it actually applies
  156.      recognizers, but this seemed clearer given the start_type_printers
  157.      and free_type_printers functions.  */
  158.   enum ext_lang_rc (*apply_type_printers)
  159.     (const struct extension_language_defn *,
  160.      const struct ext_lang_type_printers *,
  161.      struct type *, char **prettied_type);

  163.   /* Called after a type has been printed to give the type pretty-printer
  164.      mechanism an opportunity to clean up.  */
  165.   void (*free_type_printers) (const struct extension_language_defn *,
  166.                               struct ext_lang_type_printers *);

  168.   /* Try to pretty-print a value of type TYPE located at VALADDR
  169.      + EMBEDDED_OFFSET, which came from the inferior at address ADDRESS
  170.      + EMBEDDED_OFFSET, onto stdio stream STREAM according to OPTIONS.
  171.      VAL is the whole object that came from ADDRESS.  VALADDR must point to
  172.      the head of VAL's contents buffer.
  173.      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the value
  174.      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.  */
  175.   enum ext_lang_rc (*apply_val_pretty_printer)
  176.     (const struct extension_language_defn *,
  177.      struct type *type, const gdb_byte *valaddr,
  178.      int embedded_offset, CORE_ADDR address,
  179.      struct ui_file *stream, int recurse,
  180.      const struct value *val, const struct value_print_options *options,
  181.      const struct language_defn *language);

  183.   /* GDB access to the "frame filter" feature.
  184.      FRAME is the source frame to start frame-filter invocation.  FLAGS is an
  185.      integer holding the flags for printing.  The following elements of
  186.      the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
  187.      PRINT_LEVEL is a flag indicating whether to print the frame's
  188.      relative level in the output.  PRINT_FRAME_INFO is a flag that
  189.      indicates whether this function should print the frame
  190.      information, PRINT_ARGS is a flag that indicates whether to print
  191.      frame arguments, and PRINT_LOCALS, likewise, with frame local
  192.      variables.  ARGS_TYPE is an enumerator describing the argument
  193.      format, OUT is the output stream to print.  FRAME_LOW is the
  194.      beginning of the slice of frames to print, and FRAME_HIGH is the
  195.      upper limit of the frames to count.  Returns SCR_BT_ERROR on error,
  196.      or SCR_BT_COMPLETED on success.  */
  197.   enum ext_lang_bt_status (*apply_frame_filter)
  198.     (const struct extension_language_defn *,
  199.      struct frame_info *frame, int flags, enum ext_lang_frame_args args_type,
  200.      struct ui_out *out, int frame_low, int frame_high);

  202.   /* Update values held by the extension language when OBJFILE is discarded.
  203.      New global types must be created for every such value, which must then be
  204.      updated to use the new types.
  205.      This function typically just iterates over all appropriate values and
  206.      calls preserve_one_value for each one.
  207.      COPIED_TYPES is used to prevent cycles / duplicates and is passed to
  208.      preserve_one_value.  */
  209.   void (*preserve_values) (const struct extension_language_defn *,
  210.                            struct objfile *objfile, htab_t copied_types);

  212.   /* Return non-zero if there is a stop condition for the breakpoint.
  213.      This is used to implement the restriction that a breakpoint may have
  214.      at most one condition.  */
  215.   int (*breakpoint_has_cond) (const struct extension_language_defn *,
  216.                               struct breakpoint *);

  218.   /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
  219.      condition for the breakpoint, and if so whether the program should
  220.      stop.  This is called when the program has stopped at the specified
  221.      breakpoint.
  222.      While breakpoints can have at most one condition, this is called for
  223.      every extension language, even if another extension language has a
  224.      "stop" method: other kinds of breakpoints may be implemented using
  225.      this method, e.g., "finish breakpoints" in Python.  */
  226.   enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
  227.     (const struct extension_language_defn *, struct breakpoint *);

  229.   /* The next three are used to connect GDB's SIGINT handling with the
  230.      extension language's.

  232.      Terminology: If an extension language can use GDB's SIGINT handling then
  233.      we say the extension language has "cooperative SIGINT handling".
  234.      Python is an example of this.

  236.      These need not be implemented, but if one of them is implemented
  237.      then they all must be.  */

  239.   /* Clear the SIGINT indicator.  */
  240.   void (*clear_quit_flag) (const struct extension_language_defn *);

  242.   /* Set the SIGINT indicator.
  243.      This is called by GDB's SIGINT handler and must be async-safe.  */
  244.   void (*set_quit_flag) (const struct extension_language_defn *);

  246.   /* Return non-zero if a SIGINT has occurred.
  247.      This is expected to also clear the indicator.  */
  248.   int (*check_quit_flag) (const struct extension_language_defn *);

  250.   /* Called before gdb prints its prompt, giving extension languages an
  251.      opportunity to change it with set_prompt.
  252.      Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
  253.      the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
  254.      encountered.
  255.      Extension languages are called in order, and once the prompt is
  256.      changed or an error occurs no further languages are called.  */
  257.   enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
  258.                                      const char *current_gdb_prompt);

  260.   /* xmethod support:
  261.      clone_xmethod_worker_data, free_xmethod_worker_data,
  262.      get_matching_xmethod_workers, get_xmethod_arg_types,
  263.      invoke_xmethod.
  264.      These methods are optional and may be NULL, but if one of them is
  265.      implemented then they all must be.  */

  267.   /* Clone DATA and return a new but identical xmethod worker data
  268.      object for this extension language.  */
  269.   void * (*clone_xmethod_worker_data)
  270.     (const struct extension_language_defn *extlang, void *data);

  272.   /* Free the DATA object of this extension language.  */
  273.   void (*free_xmethod_worker_data)
  274.     (const struct extension_language_defn *extlang, void *data);

  276.   /* Return a vector of matching xmethod workers defined in this
  277.      extension language.  The workers service methods with name
  278.      METHOD_NAME on objects of type OBJ_TYPE.  The vector is returned
  279.      in DM_VEC.  */
  280.   enum ext_lang_rc (*get_matching_xmethod_workers)
  281.     (const struct extension_language_defn *extlang,
  282.      struct type *obj_type,
  283.      const char *method_name,
  284.      xmethod_worker_vec **dm_vec);

  286.   /* Given a WORKER servicing a particular method, return the types
  287.      of the arguments the method takes.  The number of arguments is
  288.      returned in NARGS, and their types are returned in the array
  289.      ARGTYPES.  */
  290.   enum ext_lang_rc (*get_xmethod_arg_types)
  291.     (const struct extension_language_defn *extlang,
  292.      struct xmethod_worker *worker,
  293.      int *nargs,
  294.      struct type ***arg_types);

  296.   /* Invoke the xmethod serviced by WORKER.  The xmethod is invoked
  297.      on OBJECT with arguments in the array ARGS.  NARGS is the length of
  298.      this array.  Returns the value returned by the xmethod.  */
  299.   struct value * (*invoke_xmethod)
  300.     (const struct extension_language_defn *extlang,
  301.      struct xmethod_worker *worker,
  302.      struct value *object,
  303.      struct value **args,
  304.      int nargs);
  305. };

  307. /* State necessary to restore a signal handler to its previous value.  */

  309. ‌struct signal_handler
  310. {
  311.   /* Non-zero if "handler" has been set.  */
  312.   int handler_saved;

  314.   /* The signal handler.  */
  315.   RETSIGTYPE (*handler) ();
  316. };

  318. /* State necessary to restore the currently active extension language
  319.    to its previous value.  */

  321. ‌struct active_ext_lang_state
  322. {
  323.   /* The previously active extension language.  */
  324.   const struct extension_language_defn *ext_lang;

  326.   /* Its SIGINT handler.  */
  327.   struct signal_handler sigint_handler;
  328. };

  330. extern const struct extension_language_defn *get_active_ext_lang (void);

  332. extern struct active_ext_lang_state *set_active_ext_lang
  333.   (const struct extension_language_defn *);

  335. extern void restore_active_ext_lang (struct active_ext_lang_state *previous);

  337. #endif /* EXTENSION_PRIV_H */