gdb/extension.h

   1 /* Interface between gdb and its extension languages.
   2
   3    Copyright (C) 2014-2024 Free Software Foundation, Inc.
   4
   5    This file is part of GDB.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20 #ifndef GDB_EXTENSION_H
  21 #define GDB_EXTENSION_H
  22
  23 #include "mi/mi-cmds.h"
  24 #include "gdbsupport/array-view.h"
  25 #include <optional>
  26 #include "gdbtypes.h"
  27
  28 struct breakpoint;
  29 struct command_line;
  30 class frame_info_ptr;
  31 struct language_defn;
  32 struct objfile;
  33 struct extension_language_defn;
  34 struct type;
  35 struct ui_file;
  36 struct ui_out;
  37 struct value;
  38 struct value_print_options;
  39 struct program_space;
  40
  41 /* A function to load and process a script file.
  42    The file has been opened and is ready to be read from the beginning.
  43    Any exceptions are not caught, and are passed to the caller.  */
  44 typedef void script_sourcer_func (const struct extension_language_defn *,
  45                                   FILE *stream, const char *filename);
  46
  47 /* A function to load and process a script for an objfile.
  48    The file has been opened and is ready to be read from the beginning.
  49    Any exceptions are not caught, and are passed to the caller.  */
  50 typedef void objfile_script_sourcer_func
  51   (const struct extension_language_defn *,
  52    struct objfile *, FILE *stream, const char *filename);
  53
  54 /* A function to execute a script for an objfile.
  55    Any exceptions are not caught, and are passed to the caller.  */
  56 typedef void objfile_script_executor_func
  57   (const struct extension_language_defn *,
  58    struct objfile *, const char *name, const char *script);
  59
  60 /* Enum of each extension(/scripting) language.  */
  61
  62 enum extension_language
  63   {
  64     EXT_LANG_NONE,
  65     EXT_LANG_GDB,
  66     EXT_LANG_PYTHON,
  67     EXT_LANG_GUILE
  68   };
  69
  70 /* Extension language frame-filter status return values.  */
  71
  72 enum ext_lang_bt_status
  73   {
  74     /* Return when an error has occurred in processing frame filters,
  75        or when printing the stack.  */
  76     EXT_LANG_BT_ERROR = -1,
  77
  78     /* Return from internal routines to indicate that the function
  79        succeeded.  */
  80     EXT_LANG_BT_OK = 1,
  81
  82     /* Return when the frame filter process is complete, but there
  83        were no filter registered and enabled to process.  */
  84     EXT_LANG_BT_NO_FILTERS = 2
  85   };
  86
  87 /* Flags to pass to apply_extlang_frame_filter.  */
  88
  89 enum frame_filter_flag
  90   {
  91     /* Set this flag if frame level is to be printed.  */
  92     PRINT_LEVEL = 1 << 0,
  93
  94     /* Set this flag if frame information is to be printed.  */
  95     PRINT_FRAME_INFO = 1 << 1,
  96
  97     /* Set this flag if frame arguments are to be printed.  */
  98     PRINT_ARGS = 1 << 2,
  99
 100     /* Set this flag if frame locals are to be printed.  */
 101     PRINT_LOCALS = 1 << 3,
 102
 103     /* Set this flag if a "More frames" message is to be printed.  */
 104     PRINT_MORE_FRAMES = 1 << 4,
 105
 106     /* Set this flag if elided frames should not be printed.  */
 107     PRINT_HIDE = 1 << 5,
 108
 109     /* Set this flag if pretty printers for frame arguments should not
 110        be invoked.  */
 111     PRINT_RAW_FRAME_ARGUMENTS = 1 << 6,
 112   };
 113
 114 DEF_ENUM_FLAGS_TYPE (enum frame_filter_flag, frame_filter_flags);
 115
 116 /* A choice of the different frame argument printing strategies that
 117    can occur in different cases of frame filter instantiation.  */
 118
 119 enum ext_lang_frame_args
 120   {
 121     /* Print no values for arguments when invoked from the MI. */
 122     NO_VALUES = PRINT_NO_VALUES,
 123
 124     MI_PRINT_ALL_VALUES = PRINT_ALL_VALUES,
 125
 126     /* Print only simple values (what MI defines as "simple") for
 127        arguments when invoked from the MI. */
 128     MI_PRINT_SIMPLE_VALUES = PRINT_SIMPLE_VALUES,
 129
 130     /* Print only scalar values for arguments when invoked from the CLI. */
 131     CLI_SCALAR_VALUES,
 132
 133     /* Print all values for arguments when invoked from the CLI. */
 134     CLI_ALL_VALUES,
 135
 136     /* Only indicate the presence of arguments when invoked from the CLI.  */
 137     CLI_PRESENCE
 138   };
 139
 140 /* The possible results of
 141    extension_language_ops.breakpoint_cond_says_stop.  */
 142
 143 enum ext_lang_bp_stop
 144   {
 145     /* No "stop" condition is set.  */
 146     EXT_LANG_BP_STOP_UNSET,
 147
 148     /* A "stop" condition is set, and it says "don't stop".  */
 149     EXT_LANG_BP_STOP_NO,
 150
 151     /* A "stop" condition is set, and it says "stop".  */
 152     EXT_LANG_BP_STOP_YES
 153   };
 154
 155 /* Table of type printers associated with the global typedef table.  */
 156
 157 struct ext_lang_type_printers
 158 {
 159   ext_lang_type_printers ();
 160   ~ext_lang_type_printers ();
 161
 162   DISABLE_COPY_AND_ASSIGN (ext_lang_type_printers);
 163
 164   /* Type-printers from Python.  */
 165   void *py_type_printers = nullptr;
 166 };
 167
 168 /* The return code for some API calls.  */
 169
 170 enum ext_lang_rc
 171 {
 172   /* The operation completed successfully.  */
 173   EXT_LANG_RC_OK,
 174
 175   /* The operation was not performed (e.g., no pretty-printer).  */
 176   EXT_LANG_RC_NOP,
 177
 178   /* There was an error (e.g., Python error while printing a value).
 179      When an error occurs no further extension languages are tried.
 180      This is to preserve existing behavior, and because it's convenient
 181      for Python developers.
 182      Note: This is different than encountering a memory error trying to read
 183      a value for pretty-printing.  Here we're referring to, e.g., programming
 184      errors that trigger an exception in the extension language.  */
 185   EXT_LANG_RC_ERROR
 186 };
 187
 188 /* A type which holds its extension language specific xmethod worker data.  */
 189
 190 struct xmethod_worker
 191 {
 192   xmethod_worker (const extension_language_defn *extlang)
 193   : m_extlang (extlang)
 194   {}
 195
 196   virtual ~xmethod_worker () = default;
 197
 198   /* Invoke the xmethod encapsulated in this worker and return the result.
 199      The method is invoked on OBJ with arguments in the ARGS array.  */
 200
 201   virtual value *invoke (value *obj, gdb::array_view<value *> args) = 0;
 202
 203   /* Return the arg types of the xmethod encapsulated in this worker.
 204      The type of the 'this' object is returned as the first element of
 205      the vector.  */
 206
 207   std::vector<type *> get_arg_types ();
 208
 209   /* Return the type of the result of the xmethod encapsulated in this worker.
 210      OBJECT and ARGS are the same as for invoke.  */
 211
 212   type *get_result_type (value *object, gdb::array_view<value *> args);
 213
 214 private:
 215
 216   /* Return the types of the arguments the method takes.  The types
 217      are returned in TYPE_ARGS, one per argument.  */
 218
 219   virtual enum ext_lang_rc do_get_arg_types
 220     (std::vector<type *> *type_args) = 0;
 221
 222   /* Fetch the type of the result of the method implemented by this
 223      worker.  OBJECT and ARGS are the same as for the invoked method.
 224      The result type is stored in *RESULT_TYPE.  */
 225
 226   virtual enum ext_lang_rc do_get_result_type
 227     (struct value *obj, gdb::array_view<value *> args,
 228      struct type **result_type_ptr) = 0;
 229
 230   /* The language the xmethod worker is implemented in.  */
 231
 232   const extension_language_defn *m_extlang;
 233 };
 234
 235 typedef std::unique_ptr<xmethod_worker> xmethod_worker_up;
 236
 237 /* The interface for gdb's own extension(/scripting) language.  */
 238 extern const struct extension_language_defn extension_language_gdb;
 239
 240 extern const struct extension_language_defn *get_ext_lang_defn
 241   (enum extension_language lang);
 242
 243 extern const struct extension_language_defn *get_ext_lang_of_file
 244   (const char *file);
 245
 246 extern int ext_lang_present_p (const struct extension_language_defn *);
 247
 248 extern int ext_lang_initialized_p (const struct extension_language_defn *);
 249
 250 extern void throw_ext_lang_unsupported
 251   (const struct extension_language_defn *);
 252
 253 /* Accessors for "public" attributes of the extension language definition.  */
 254
 255 extern enum extension_language ext_lang_kind
 256   (const struct extension_language_defn *);
 257
 258 extern const char *ext_lang_name (const struct extension_language_defn *);
 259
 260 extern const char *ext_lang_capitalized_name
 261   (const struct extension_language_defn *);
 262
 263 extern const char *ext_lang_suffix (const struct extension_language_defn *);
 264
 265 extern const char *ext_lang_auto_load_suffix
 266   (const struct extension_language_defn *);
 267
 268 extern script_sourcer_func *ext_lang_script_sourcer
 269   (const struct extension_language_defn *);
 270
 271 extern objfile_script_sourcer_func *ext_lang_objfile_script_sourcer
 272   (const struct extension_language_defn *);
 273
 274 extern objfile_script_executor_func *ext_lang_objfile_script_executor
 275   (const struct extension_language_defn *);
 276
 277 /* Return true if auto-loading of EXTLANG scripts is enabled.
 278    False is returned if support for this language isn't compiled in.  */
 279
 280 extern bool ext_lang_auto_load_enabled (const struct extension_language_defn *);
 281
 282 /* Wrappers for each extension language API function that iterate over all
 283    extension languages.  */
 284
 285 extern void ext_lang_initialization (void);
 286
 287 /* Shut down all extension languages.  */
 288 extern void ext_lang_shutdown ();
 289
 290 extern void eval_ext_lang_from_control_command (struct command_line *cmd);
 291
 292 extern void auto_load_ext_lang_scripts_for_objfile (struct objfile *);
 293
 294 extern gdb::unique_xmalloc_ptr<char> apply_ext_lang_type_printers
 295      (struct ext_lang_type_printers *, struct type *);
 296
 297 extern int apply_ext_lang_val_pretty_printer
 298   (struct value *value, struct ui_file *stream, int recurse,
 299    const struct value_print_options *options,
 300    const struct language_defn *language);
 301
 302 extern enum ext_lang_bt_status apply_ext_lang_frame_filter
 303   (const frame_info_ptr &frame, frame_filter_flags flags,
 304    enum ext_lang_frame_args args_type,
 305    struct ui_out *out, int frame_low, int frame_high);
 306
 307 extern void apply_ext_lang_ptwrite_filter
 308   (struct btrace_thread_info *btinfo);
 309
 310 extern void preserve_ext_lang_values (struct objfile *,
 311                                       copied_types_hash_t &copied_types);
 312
 313 extern const struct extension_language_defn *get_breakpoint_cond_ext_lang
 314   (struct breakpoint *b, enum extension_language skip_lang);
 315
 316 extern bool breakpoint_ext_lang_cond_says_stop (struct breakpoint *);
 317
 318 /* If a method with name METHOD_NAME is to be invoked on an object of type
 319    TYPE, then all extension languages are searched for implementations of
 320    methods with name METHOD_NAME.  All matches found are appended to the WORKERS
 321    vector.  */
 322
 323 extern void get_matching_xmethod_workers
 324   (struct type *type, const char *method_name,
 325    std::vector<xmethod_worker_up> *workers);
 326
 327 /* Try to colorize some source code.  FILENAME is the name of the file
 328    holding the code.  CONTENTS is the source code itself.  This will
 329    either a colorized (using ANSI terminal escapes) version of the
 330    source code, or an empty value if colorizing could not be done.  */
 331
 332 extern std::optional<std::string> ext_lang_colorize
 333   (const std::string &filename, const std::string &contents);
 334
 335 /* Try to colorize a single line of disassembler output, CONTENT for
 336    GDBARCH.  This will return either a colorized (using ANSI terminal
 337    escapes) version of CONTENT, or an empty value if colorizing could not
 338    be done.  */
 339
 340 extern std::optional<std::string> ext_lang_colorize_disasm
 341   (const std::string &content, gdbarch *gdbarch);
 342
 343 /* Calls extension_language_ops::print_insn for each extension language,
 344    returning the result from the first extension language that returns a
 345    non-empty result (any further extension languages are not then called).
 346
 347    All arguments are forwarded to extension_language_ops::print_insn, see
 348    that function for a full description.  */
 349
 350 extern std::optional<int> ext_lang_print_insn
 351   (struct gdbarch *gdbarch, CORE_ADDR address, struct disassemble_info *info);
 352
 353 /* When GDB calls into an extension language because an objfile was
 354    discovered for which GDB couldn't find any debug information, this
 355    structure holds the result that the extension language returns.
 356
 357    There are three possible actions that might be returned by an extension;
 358    first an extension can return a filename, this is the path to the file
 359    containing the required debug  information.  The second possibility is
 360    to return a flag indicating that GDB should check again for the missing
 361    debug information, this would imply that the extension has installed
 362    the debug information into a location where GDB can be expected to find
 363    it.  And the third option is for the extension to just return a null
 364    result, indication there is nothing the extension can do to provide the
 365    missing debug information.  */
 366 struct ext_lang_missing_file_result
 367 {
 368   /* Default result.  The extension was unable to provide the missing debug
 369      info.  */
 370   ext_lang_missing_file_result ()
 371   { /* Nothing.  */ }
 372
 373   /* When TRY_AGAIN is true GDB should try searching again, the extension
 374      may have installed the missing debug info into a suitable location.
 375      When TRY_AGAIN is false this is equivalent to the default, no
 376      argument, constructor.  */
 377   ext_lang_missing_file_result (bool try_again)
 378     : m_try_again (try_again)
 379   { /* Nothing.  */ }
 380
 381   /* Look in FILENAME for the missing debug info.  */
 382   ext_lang_missing_file_result (std::string &&filename)
 383     : m_filename (std::move (filename))
 384   { /* Nothing.  */ }
 385
 386   /* The filename where GDB can find the missing debuginfo.  This is empty
 387      if the extension didn't suggest a file that can be used.  */
 388   const std::string &
 389   filename () const
 390   {
 391     return m_filename;
 392   }
 393
 394   /* Returns true if GDB should look again for the debug information.  */
 395   const bool
 396   try_again () const
 397   {
 398     return m_try_again;
 399   }
 400
 401 private:
 402   /* The filename where the missing debuginfo can now be found.  */
 403   std::string m_filename;
 404
 405   /* When true GDB will search again for the debuginfo using its standard
 406      techniques.  When false GDB will not search again.  */
 407   bool m_try_again = false;
 408 };
 409
 410 /* Called when GDB failed to find any debug information for OBJFILE.  */
 411
 412 extern ext_lang_missing_file_result ext_lang_handle_missing_debuginfo
 413   (struct objfile *objfile);
 414
 415 /* Called when GDB opens a core-file to find any object files for which a
 416    build-id could be extracted from the core-file, but the matching file
 417    could not otherwise be found by GDB.
 418
 419    PSPACE is the program space in which GDB is opening the core-file and
 420    is looking for a missing object file.  BUILD_ID is the build-id of the
 421    file being looked for, and will not be NULL.  FILENAME is the name of
 422    the file GDB is looking for, this will not be NULL.  The FILENAME is
 423    provided only for creating helpful messages for the user.  FILENAME
 424    might already exist on disk but have the wrong build-id, of FILENAME
 425    might not exist on disk.  If the missing objfile can be found then it
 426    does not have to be placed at the location FILENAME.
 427
 428    The returned object indicates if the file could be found or not.  */
 429
 430 extern ext_lang_missing_file_result ext_lang_find_objfile_from_buildid
 431   (program_space *pspace, const struct bfd_build_id *build_id,
 432    const char *filename);
 433
 434 #if GDB_SELF_TEST
 435 namespace selftests {
 436 extern void (*hook_set_active_ext_lang) ();
 437 }
 438 #endif
 439
 440 /* Temporarily disable cooperative SIGINT handling.  Needed when we
 441    don't want a SIGINT to interrupt the currently active extension
 442    language.  */
 443 class scoped_disable_cooperative_sigint_handling
 444 {
 445 public:
 446   scoped_disable_cooperative_sigint_handling ();
 447   ~scoped_disable_cooperative_sigint_handling ();
 448
 449   DISABLE_COPY_AND_ASSIGN (scoped_disable_cooperative_sigint_handling);
 450
 451 private:
 452   struct active_ext_lang_state *m_prev_active_ext_lang_state;
 453   bool m_prev_cooperative_sigint_handling_disabled;
 454 };
 455
 456 /* GDB's SIGINT handler basically sets a flag; code that might take a
 457    long time before it gets back to the event loop, and which ought to
 458    be interruptible, checks this flag using the QUIT macro, which, if
 459    GDB has the terminal, throws a quit exception.
 460
 461    In addition to setting a flag, the SIGINT handler also marks a
 462    select/poll-able file descriptor as read-ready.  That is used by
 463    interruptible_select in order to support interrupting blocking I/O
 464    in a race-free manner.
 465
 466    These functions use the extension_language_ops API to allow extension
 467    language(s) and GDB SIGINT handling to coexist seamlessly.  */
 468
 469 /* Return true if the quit flag has been set, false otherwise.
 470    Note: The flag is cleared as a side-effect.
 471    The flag is checked in all extension languages that support cooperative
 472    SIGINT handling, not just the current one.  This simplifies transitions.  */
 473
 474 extern bool check_quit_flag ();
 475
 476 /* Set the quit flag.
 477    This only sets the flag in the currently active extension language.
 478    If the currently active extension language does not have cooperative
 479    SIGINT handling, then GDB's global flag is set, and it is up to the
 480    extension language to call check_quit_flag.  The extension language
 481    is free to install its own SIGINT handler, but we still need to handle
 482    the transition.  */
 483
 484 extern void set_quit_flag ();
 485
 486 #endif /* GDB_EXTENSION_H */