gdb/extension-priv.h

   1 /* Private implementation details of interface between gdb and its
   2    extension languages.
   3
   4    Copyright (C) 2014-2024 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 /* High level description of an extension/scripting language.
  29    An entry for each is compiled into GDB regardless of whether the support
  30    is present.  This is done so that we can issue meaningful errors if the
  31    support is not compiled in.  */
  32
  33 struct extension_language_defn
  34 {
  35   /* Enum of the extension language.  */
  36   enum extension_language language;
  37
  38   /* The name of the extension language, lowercase.  E.g., python.  */
  39   const char *name;
  40
  41   /* The capitalized name of the extension language.
  42      For python this is "Python".  For gdb this is "GDB".  */
  43   const char *capitalized_name;
  44
  45   /* The file suffix of this extension language.  E.g., ".py".  */
  46   const char *suffix;
  47
  48   /* The suffix of per-objfile scripts to auto-load.
  49      E.g., When the program loads libfoo.so, look for libfoo.so-gdb.py.  */
  50   const char *auto_load_suffix;
  51
  52   /* We support embedding external extension language code in GDB's own
  53      scripting language.  We do this by having a special command that begins
  54      the extension language snippet, and terminate it with "end".
  55      This specifies the control type used to implement this.  */
  56   enum command_control_type cli_control_type;
  57
  58   /* A pointer to the "methods" to load scripts in this language,
  59      or NULL if the support is not compiled into GDB.  */
  60   const struct extension_language_script_ops *script_ops;
  61
  62   /* Either a pointer to the "methods" of the extension language interface
  63      or NULL if the support is not compiled into GDB.
  64      This is also NULL for GDB's own scripting language which is relatively
  65      primitive, and doesn't provide these features.  */
  66   const struct extension_language_ops *ops;
  67 };
  68
  69 /* The interface for loading scripts from external extension languages,
  70    as well as GDB's own scripting language.
  71    All of these methods are required to be implemented.
  72
  73    By convention all of these functions take a pseudo-this parameter
  74    as the first argument.  */
  75
  76 struct extension_language_script_ops
  77 {
  78   /* Load a script.  This is called, e.g., via the "source" command.
  79      If there's an error while processing the script this function may,
  80      but is not required to, throw an error.  */
  81   script_sourcer_func *script_sourcer;
  82
  83   /* Load a script attached to an objfile.
  84      If there's an error while processing the script this function may,
  85      but is not required to, throw an error.  */
  86   objfile_script_sourcer_func *objfile_script_sourcer;
  87
  88   /* Execute a script attached to an objfile.
  89      If there's an error while processing the script this function may,
  90      but is not required to, throw an error.  */
  91   objfile_script_executor_func *objfile_script_executor;
  92
  93   /* Return non-zero if auto-loading scripts in this extension language
  94      is enabled.  */
  95   bool (*auto_load_enabled) (const struct extension_language_defn *);
  96 };
  97
  98 /* The interface for making calls from GDB to an external extension
  99    language.  This is for non-script-loading related functionality, like
 100    pretty-printing, etc.  The reason these are separated out is GDB's own
 101    scripting language makes use of extension_language_script_opts, but it
 102    makes no use of these.  There is no (current) intention to split
 103    extension_language_ops up any further.
 104    All of these methods are optional and may be NULL, except where
 105    otherwise indicated.
 106
 107    By convention all of these functions take a pseudo-this parameter
 108    as the first argument.  */
 109
 110 struct extension_language_ops
 111 {
 112   /* Called after GDB has processed the early initialization settings
 113      files.  This is when the extension language should be initialized.  By
 114      the time this is called all of the earlier initialization functions
 115      have already been called.  */
 116   void (*initialize) (const struct extension_language_defn *);
 117
 118   /* Return non-zero if the extension language successfully initialized.
 119      This method is required.  */
 120   int (*initialized) (const struct extension_language_defn *);
 121
 122   /* Called just before GDB exits.  This shuts down the extension
 123      language.  This can be NULL.  */
 124   void (*shutdown) (const struct extension_language_defn *);
 125
 126   /* Process a sequence of commands embedded in GDB's own scripting language.
 127      E.g.,
 128      python
 129      print 42
 130      end  */
 131   void (*eval_from_control_command) (const struct extension_language_defn *,
 132                                      struct command_line *);
 133
 134   /* Type-printing support:
 135      start_type_printers, apply_type_printers, free_type_printers.
 136      These methods are optional and may be NULL, but if one of them is
 137      implemented then they all must be.  */
 138
 139   /* Called before printing a type.  */
 140   void (*start_type_printers) (const struct extension_language_defn *,
 141                                struct ext_lang_type_printers *);
 142
 143   /* Try to pretty-print TYPE.  If successful the pretty-printed type is
 144      stored in *PRETTIED_TYPE.
 145      Returns EXT_LANG_RC_OK upon success, EXT_LANG_RC_NOP if the type
 146      is not recognized, and EXT_LANG_RC_ERROR if an error was encountered.
 147      This function has a bit of a funny name, since it actually applies
 148      recognizers, but this seemed clearer given the start_type_printers
 149      and free_type_printers functions.  */
 150   enum ext_lang_rc (*apply_type_printers)
 151     (const struct extension_language_defn *,
 152      const struct ext_lang_type_printers *,
 153      struct type *,
 154      gdb::unique_xmalloc_ptr<char> *prettied_type);
 155
 156   /* Called after a type has been printed to give the type pretty-printer
 157      mechanism an opportunity to clean up.  */
 158   void (*free_type_printers) (const struct extension_language_defn *,
 159                               struct ext_lang_type_printers *);
 160
 161   /* Try to pretty-print a value, onto stdio stream STREAM according
 162      to OPTIONS.  VAL is the object to print.  Returns EXT_LANG_RC_OK
 163      upon success, EXT_LANG_RC_NOP if the value is not recognized, and
 164      EXT_LANG_RC_ERROR if an error was encountered.  */
 165   enum ext_lang_rc (*apply_val_pretty_printer)
 166     (const struct extension_language_defn *,
 167      struct value *val, struct ui_file *stream, int recurse,
 168      const struct value_print_options *options,
 169      const struct language_defn *language);
 170
 171   /* GDB access to the "frame filter" feature.
 172      FRAME is the source frame to start frame-filter invocation.  FLAGS is an
 173      integer holding the flags for printing.  The following elements of
 174      the FRAME_FILTER_FLAGS enum denotes the make-up of FLAGS:
 175      PRINT_LEVEL is a flag indicating whether to print the frame's
 176      relative level in the output.  PRINT_FRAME_INFO is a flag that
 177      indicates whether this function should print the frame
 178      information, PRINT_ARGS is a flag that indicates whether to print
 179      frame arguments, and PRINT_LOCALS, likewise, with frame local
 180      variables.  ARGS_TYPE is an enumerator describing the argument
 181      format, OUT is the output stream to print.  FRAME_LOW is the
 182      beginning of the slice of frames to print, and FRAME_HIGH is the
 183      upper limit of the frames to count.  Returns SCR_BT_ERROR on error,
 184      or SCR_BT_COMPLETED on success.  */
 185   enum ext_lang_bt_status (*apply_frame_filter)
 186     (const struct extension_language_defn *,
 187      const frame_info_ptr &frame, frame_filter_flags flags,
 188      enum ext_lang_frame_args args_type,
 189      struct ui_out *out, int frame_low, int frame_high);
 190
 191   /* Update values held by the extension language when OBJFILE is discarded.
 192      New global types must be created for every such value, which must then be
 193      updated to use the new types.
 194      This function typically just iterates over all appropriate values and
 195      calls preserve_one_value for each one.
 196      COPIED_TYPES is used to prevent cycles / duplicates and is passed to
 197      preserve_one_value.  */
 198   void (*preserve_values) (const struct extension_language_defn *,
 199                            struct objfile *objfile, htab_t copied_types);
 200
 201   /* Return non-zero if there is a stop condition for the breakpoint.
 202      This is used to implement the restriction that a breakpoint may have
 203      at most one condition.  */
 204   int (*breakpoint_has_cond) (const struct extension_language_defn *,
 205                               struct breakpoint *);
 206
 207   /* Return a value of enum ext_lang_bp_stop indicating if there is a stop
 208      condition for the breakpoint, and if so whether the program should
 209      stop.  This is called when the program has stopped at the specified
 210      breakpoint.
 211      While breakpoints can have at most one condition, this is called for
 212      every extension language, even if another extension language has a
 213      "stop" method: other kinds of breakpoints may be implemented using
 214      this method, e.g., "finish breakpoints" in Python.  */
 215   enum ext_lang_bp_stop (*breakpoint_cond_says_stop)
 216     (const struct extension_language_defn *, struct breakpoint *);
 217
 218   /* The next two are used to connect GDB's SIGINT handling with the
 219      extension language's.
 220
 221      Terminology: If an extension language can use GDB's SIGINT handling then
 222      we say the extension language has "cooperative SIGINT handling".
 223      Python is an example of this.
 224
 225      These need not be implemented, but if one of them is implemented
 226      then they all must be.  */
 227
 228   /* Set the SIGINT indicator.
 229      This is called by GDB's SIGINT handler and must be async-safe.  */
 230   void (*set_quit_flag) (const struct extension_language_defn *);
 231
 232   /* Return non-zero if a SIGINT has occurred.
 233      This is expected to also clear the indicator.  */
 234   int (*check_quit_flag) (const struct extension_language_defn *);
 235
 236   /* Called before gdb prints its prompt, giving extension languages an
 237      opportunity to change it with set_prompt.
 238      Returns EXT_LANG_RC_OK if the prompt was changed, EXT_LANG_RC_NOP if
 239      the prompt was not changed, and EXT_LANG_RC_ERROR if an error was
 240      encountered.
 241      Extension languages are called in order, and once the prompt is
 242      changed or an error occurs no further languages are called.  */
 243   enum ext_lang_rc (*before_prompt) (const struct extension_language_defn *,
 244                                      const char *current_gdb_prompt);
 245
 246   /* Return a vector of matching xmethod workers defined in this
 247      extension language.  The workers service methods with name
 248      METHOD_NAME on objects of type OBJ_TYPE.  The vector is returned
 249      in DM_VEC.
 250
 251      This field may be NULL if the extension language does not support
 252      xmethods.  */
 253   enum ext_lang_rc (*get_matching_xmethod_workers)
 254     (const struct extension_language_defn *extlang,
 255      struct type *obj_type,
 256      const char *method_name,
 257      std::vector<xmethod_worker_up> *dm_vec);
 258
 259   /* Colorize a source file.  NAME is the source file's name, and
 260      CONTENTS is the contents of the file.  This should either return
 261      colorized (using ANSI terminal escapes) version of the contents,
 262      or an empty option.  */
 263   std::optional<std::string> (*colorize) (const std::string &name,
 264                                           const std::string &contents);
 265
 266   /* Colorize a single line of disassembler output, CONTENT.  This should
 267      either return colorized (using ANSI terminal escapes) version of the
 268      contents, or an empty optional.  */
 269   std::optional<std::string> (*colorize_disasm) (const std::string &content,
 270                                                  gdbarch *gdbarch);
 271
 272   /* Print a single instruction from ADDRESS in architecture GDBARCH.  INFO
 273      is the standard libopcodes disassembler_info structure.  Bytes for the
 274      instruction being printed should be read using INFO->read_memory_func
 275      as the actual instruction bytes might be in a buffer.
 276
 277      Use INFO->fprintf_func to print the results of the disassembly, and
 278      return the length of the instruction.
 279
 280      If no instruction can be disassembled then return an empty value and
 281      other extension languages will get a chance to perform the
 282      disassembly.  */
 283   std::optional<int> (*print_insn) (struct gdbarch *gdbarch,
 284                                     CORE_ADDR address,
 285                                     struct disassemble_info *info);
 286
 287   /* Give extension languages a chance to deal with missing debug
 288      information.  OBJFILE is the file for which GDB was unable to find
 289      any debug information.  */
 290   ext_lang_missing_debuginfo_result
 291     (*handle_missing_debuginfo) (const struct extension_language_defn *,
 292                                  struct objfile *objfile);
 293 };
 294
 295 /* State necessary to restore a signal handler to its previous value.  */
 296
 297 struct signal_handler
 298 {
 299   /* Non-zero if "handler" has been set.  */
 300   int handler_saved;
 301
 302   /* The signal handler.  */
 303   sighandler_t handler;
 304 };
 305
 306 /* State necessary to restore the currently active extension language
 307    to its previous value.  */
 308
 309 struct active_ext_lang_state
 310 {
 311   /* The previously active extension language.  */
 312   const struct extension_language_defn *ext_lang;
 313
 314   /* Its SIGINT handler.  */
 315   struct signal_handler sigint_handler;
 316 };
 317
 318 extern struct active_ext_lang_state *set_active_ext_lang
 319   (const struct extension_language_defn *);
 320
 321 extern void restore_active_ext_lang (struct active_ext_lang_state *previous);
 322
 323 #endif /* EXTENSION_PRIV_H */