gdb/interps.h

   1 /* Manages interpreters for GDB, the GNU debugger.
   2
   3    Copyright (C) 2000-2024 Free Software Foundation, Inc.
   4
   5    Written by Jim Ingham <jingham@apple.com> of Apple Computer, Inc.
   6
   7    This file is part of GDB.
   8
   9    This program is free software; you can redistribute it and/or modify
  10    it under the terms of the GNU General Public License as published by
  11    the Free Software Foundation; either version 3 of the License, or
  12    (at your option) any later version.
  13
  14    This program is distributed in the hope that it will be useful,
  15    but WITHOUT ANY WARRANTY; without even the implied warranty of
  16    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17    GNU General Public License for more details.
  18
  19    You should have received a copy of the GNU General Public License
  20    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  21
  22 #ifndef INTERPS_H
  23 #define INTERPS_H
  24
  25 #include "gdbsupport/intrusive_list.h"
  26
  27 struct bpstat;
  28 struct ui_out;
  29 struct interp;
  30 struct ui;
  31 class completion_tracker;
  32 struct thread_info;
  33 struct inferior;
  34 struct solib;
  35 struct trace_state_variable;
  36
  37 typedef struct interp *(*interp_factory_func) (const char *name);
  38
  39 /* Each interpreter kind (CLI, MI, etc.) registers itself with a call
  40    to this function, passing along its name, and a pointer to a
  41    function that creates a new instance of an interpreter with that
  42    name.
  43
  44    The memory for NAME must have static storage duration.  */
  45 extern void interp_factory_register (const char *name,
  46                                      interp_factory_func func);
  47
  48 extern void interp_exec (struct interp *interp, const char *command);
  49
  50 class interp : public intrusive_list_node<interp>
  51 {
  52 public:
  53   explicit interp (const char *name);
  54   virtual ~interp () = 0;
  55
  56   virtual void init (bool top_level)
  57   {}
  58
  59   virtual void resume () = 0;
  60   virtual void suspend () = 0;
  61
  62   virtual void exec (const char *command) = 0;
  63
  64   /* Returns the ui_out currently used to collect results for this
  65      interpreter.  It can be a formatter for stdout, as is the case
  66      for the console & mi outputs, or it might be a result
  67      formatter.  */
  68   virtual ui_out *interp_ui_out () = 0;
  69
  70   /* Provides a hook for interpreters to do any additional
  71      setup/cleanup that they might need when logging is enabled or
  72      disabled.  */
  73   virtual void set_logging (ui_file_up logfile, bool logging_redirect,
  74                             bool debug_redirect) = 0;
  75
  76   /* Called before starting an event loop, to give the interpreter a
  77      chance to e.g., print a prompt.  */
  78   virtual void pre_command_loop ()
  79   {}
  80
  81   /* Returns true if this interpreter supports using the readline
  82      library; false if it uses GDB's own simplified readline
  83      emulation.  */
  84   virtual bool supports_command_editing ()
  85   { return false; }
  86
  87   /* Returns true if this interpreter supports new UIs.  */
  88   virtual bool supports_new_ui () const
  89   { return true; }
  90
  91   const char *name () const
  92   { return m_name; }
  93
  94   /* Notify the interpreter that the current inferior has stopped with signal
  95      SIG.  */
  96   virtual void on_signal_received (gdb_signal sig) {}
  97
  98   /* Notify the interpreter that the current inferior has exited with signal
  99      SIG. */
 100   virtual void on_signal_exited (gdb_signal sig) {}
 101
 102   /* Notify the interpreter that the current inferior has stopped normally.  */
 103   virtual void on_normal_stop (bpstat *bs, int print_frame) {}
 104
 105   /* Notify the interpreter that the current inferior has exited normally with
 106      status STATUS.  */
 107   virtual void on_exited (int status) {}
 108
 109   /* Notify the interpreter that the current inferior has stopped reverse
 110      execution because there is no more history.  */
 111   virtual void on_no_history () {}
 112
 113   /* Notify the interpreter that a synchronous command it started has
 114      finished.  */
 115   virtual void on_sync_execution_done () {}
 116
 117   /* Notify the interpreter that an error was caught while executing a
 118      command on this interpreter.  */
 119   virtual void on_command_error () {}
 120
 121   /* Notify the interpreter that the user focus has changed.  */
 122   virtual void on_user_selected_context_changed (user_selected_what selection)
 123     {}
 124
 125   /* Notify the interpreter that thread T has been created.  */
 126   virtual void on_new_thread (thread_info *t) {}
 127
 128   /* Notify the interpreter that thread T has exited.  */
 129   virtual void on_thread_exited (thread_info *,
 130                                  std::optional<ULONGEST> exit_code,
 131                                  int silent) {}
 132
 133   /* Notify the interpreter that inferior INF was added.  */
 134   virtual void on_inferior_added (inferior *inf) {}
 135
 136   /* Notify the interpreter that inferior INF was started or attached.  */
 137   virtual void on_inferior_appeared (inferior *inf) {}
 138
 139   /* Notify the interpreter that inferior INF exited or was detached.  */
 140   virtual void on_inferior_disappeared (inferior *inf) {}
 141
 142   /* Notify the interpreter that inferior INF was removed.  */
 143   virtual void on_inferior_removed (inferior *inf) {}
 144
 145   /* Notify the interpreter that the status of process record for INF
 146      changed.  */
 147   virtual void on_record_changed (inferior *inf, int started,
 148                                   const char *method, const char *format) {}
 149
 150   /* Notify the interpreter that the target was resumed.  */
 151   virtual void on_target_resumed (ptid_t ptid) {}
 152
 153   /* Notify the interpreter that solib SO has been loaded.  */
 154   virtual void on_solib_loaded (const solib &so) {}
 155
 156   /* Notify the interpreter that solib SO has been unloaded.  */
 157   virtual void on_solib_unloaded (const solib &so) {}
 158
 159   /* Notify the interpreter that a command it is executing is about to cause
 160      the inferior to proceed.  */
 161   virtual void on_about_to_proceed () {}
 162
 163   /* Notify the interpreter that the selected traceframe changed.  */
 164   virtual void on_traceframe_changed (int tfnum, int tpnum) {}
 165
 166   /* Notify the interpreter that trace state variable TSV was created.  */
 167   virtual void on_tsv_created (const trace_state_variable *tsv) {}
 168
 169   /* Notify the interpreter that trace state variable TSV was deleted.  */
 170   virtual void on_tsv_deleted (const trace_state_variable *tsv) {}
 171
 172   /* Notify the interpreter that trace state variable TSV was modified.  */
 173   virtual void on_tsv_modified (const trace_state_variable *tsv) {}
 174
 175   /* Notify the interpreter that breakpoint B was created.  */
 176   virtual void on_breakpoint_created (breakpoint *b) {}
 177
 178   /* Notify the interpreter that breakpoint B was deleted.  */
 179   virtual void on_breakpoint_deleted (breakpoint *b) {}
 180
 181   /* Notify the interpreter that breakpoint B was modified.  */
 182   virtual void on_breakpoint_modified (breakpoint *b) {}
 183
 184   /* Notify the interpreter that parameter PARAM changed to VALUE.  */
 185   virtual void on_param_changed (const char *param, const char *value) {}
 186
 187   /* Notify the interpreter that inferior INF's memory was changed.  */
 188   virtual void on_memory_changed (inferior *inf, CORE_ADDR addr, ssize_t len,
 189                                   const bfd_byte *data) {}
 190
 191 private:
 192   /* The memory for this is static, it comes from literal strings (e.g. "cli").  */
 193   const char *m_name;
 194
 195 public:
 196   /* Has the init method been run?  */
 197   bool inited = false;
 198 };
 199
 200 /* Look up the interpreter for NAME, creating one if none exists yet.
 201    If NAME is not a interpreter type previously registered with
 202    interp_factory_register, return NULL; otherwise return a pointer to
 203    the interpreter.  */
 204 extern struct interp *interp_lookup (struct ui *ui, const char *name);
 205
 206 /* Set the current UI's top level interpreter to the interpreter named
 207    NAME.  Throws an error if NAME is not a known interpreter or the
 208    interpreter fails to initialize.  FOR_NEW_UI is true when called
 209    from the 'new-ui' command, and causes an extra check to ensure the
 210    interpreter is valid for a new UI.  */
 211 extern void set_top_level_interpreter (const char *name, bool for_new_ui);
 212
 213 /* Temporarily set the current interpreter, and reset it on
 214    destruction.  */
 215 class scoped_restore_interp
 216 {
 217 public:
 218
 219   scoped_restore_interp (const char *name)
 220     : m_interp (set_interp (name))
 221   {
 222   }
 223
 224   ~scoped_restore_interp ()
 225   {
 226     set_interp (m_interp->name ());
 227   }
 228
 229   scoped_restore_interp (const scoped_restore_interp &) = delete;
 230   scoped_restore_interp &operator= (const scoped_restore_interp &) = delete;
 231
 232 private:
 233
 234   struct interp *set_interp (const char *name);
 235
 236   struct interp *m_interp;
 237 };
 238
 239 extern int current_interp_named_p (const char *name);
 240
 241 /* Call this function to give the current interpreter an opportunity
 242    to do any special handling of streams when logging is enabled or
 243    disabled.  LOGFILE is the stream for the log file when logging is
 244    starting and is NULL when logging is ending.  LOGGING_REDIRECT is
 245    the value of the "set logging redirect" setting.  If true, the
 246    interpreter should configure the output streams to send output only
 247    to the logfile.  If false, the interpreter should configure the
 248    output streams to send output to both the current output stream
 249    (i.e., the terminal) and the log file.  DEBUG_REDIRECT is same as
 250    LOGGING_REDIRECT, but for the value of "set logging debugredirect"
 251    instead.  */
 252 extern void current_interp_set_logging (ui_file_up logfile,
 253                                         bool logging_redirect,
 254                                         bool debug_redirect);
 255
 256 /* Returns the top-level interpreter.  */
 257 extern struct interp *top_level_interpreter (void);
 258
 259 /* Return the current UI's current interpreter.  */
 260 extern struct interp *current_interpreter (void);
 261
 262 extern struct interp *command_interp (void);
 263
 264 extern void clear_interpreter_hooks (void);
 265
 266 /* List the possible interpreters which could complete the given
 267    text.  */
 268 extern void interpreter_completer (struct cmd_list_element *ignore,
 269                                    completion_tracker &tracker,
 270                                    const char *text,
 271                                    const char *word);
 272
 273 /* Notify all interpreters that the current inferior has stopped with signal
 274    SIG.  */
 275 extern void interps_notify_signal_received (gdb_signal sig);
 276
 277 /* Notify all interpreters that the current inferior has exited with signal
 278    SIG.  */
 279 extern void interps_notify_signal_exited (gdb_signal sig);
 280
 281 /* Notify all interpreters that the current inferior has stopped normally.  */
 282 extern void interps_notify_normal_stop (bpstat *bs, int print_frame);
 283
 284 /* Notify all interpreters that the current inferior has stopped reverse
 285    execution because there is no more history.  */
 286 extern void interps_notify_no_history ();
 287
 288 /* Notify all interpreters that the current inferior has exited normally with
 289    status STATUS.  */
 290 extern void interps_notify_exited (int status);
 291
 292 /* Notify all interpreters that the user focus has changed.  */
 293 extern void interps_notify_user_selected_context_changed
 294   (user_selected_what selection);
 295
 296 /* Notify all interpreters that thread T has been created.  */
 297 extern void interps_notify_new_thread (thread_info *t);
 298
 299 /* Notify all interpreters that thread T has exited.  */
 300 extern void interps_notify_thread_exited (thread_info *t,
 301                                           std::optional<ULONGEST> exit_code,
 302                                           int silent);
 303
 304 /* Notify all interpreters that inferior INF was added.  */
 305 extern void interps_notify_inferior_added (inferior *inf);
 306
 307 /* Notify all interpreters that inferior INF was started or attached.  */
 308 extern void interps_notify_inferior_appeared (inferior *inf);
 309
 310 /* Notify all interpreters that inferior INF exited or was detached.  */
 311 extern void interps_notify_inferior_disappeared (inferior *inf);
 312
 313 /* Notify all interpreters that inferior INF was removed.  */
 314 extern void interps_notify_inferior_removed (inferior *inf);
 315
 316 /* Notify all interpreters that the status of process record for INF changed.
 317
 318    The process record is started if STARTED is true, and the process record is
 319    stopped if STARTED is false.
 320
 321    When STARTED is true, METHOD indicates the short name of the method used for
 322    recording.  If the method supports multiple formats, FORMAT indicates which
 323    one is being used, otherwise it is nullptr.  When STARTED is false, they are
 324    both nullptr.  */
 325 extern void interps_notify_record_changed (inferior *inf, int started,
 326                                            const char *method,
 327                                            const char *format);
 328
 329 /* Notify all interpreters that the target was resumed.  */
 330 extern void interps_notify_target_resumed (ptid_t ptid);
 331
 332 /* Notify all interpreters that solib SO has been loaded.  */
 333 extern void interps_notify_solib_loaded (const solib &so);
 334
 335 /* Notify all interpreters that solib SO has been unloaded.  */
 336 extern void interps_notify_solib_unloaded (const solib &so);
 337
 338 /* Notify all interpreters that the selected traceframe changed.
 339
 340    The trace frame is changed to TFNUM (e.g., by using the 'tfind' command).
 341    If TFNUM is negative, it means gdb resumed live debugging.  The number of
 342    the tracepoint associated with this traceframe is TPNUM.  */
 343 extern void interps_notify_traceframe_changed (int tfnum, int tpnum);
 344
 345 /* Notify all interpreters that trace state variable TSV was created.  */
 346 extern void interps_notify_tsv_created (const trace_state_variable *tsv);
 347
 348 /* Notify all interpreters that trace state variable TSV was deleted.
 349
 350    If TSV is nullptr, it means that all trace state variables were deleted.  */
 351 extern void interps_notify_tsv_deleted (const trace_state_variable *tsv);
 352
 353 /* Notify all interpreters that trace state variable TSV was modified.  */
 354 extern void interps_notify_tsv_modified (const trace_state_variable *tsv);
 355
 356 /* Notify all interpreters that breakpoint B was created.  */
 357 extern void interps_notify_breakpoint_created (breakpoint *b);
 358
 359 /* Notify all interpreters that breakpoint B was deleted.  */
 360 extern void interps_notify_breakpoint_deleted (breakpoint *b);
 361
 362 /* Notify all interpreters that breakpoint B was modified.  */
 363 extern void interps_notify_breakpoint_modified (breakpoint *b);
 364
 365 /* Notify all interpreters that parameter PARAM changed to VALUE.  */
 366 extern void interps_notify_param_changed (const char *param, const char *value);
 367
 368 /* Notify all interpreters that inferior INF's memory was changed.  */
 369 extern void interps_notify_memory_changed (inferior *inf, CORE_ADDR addr,
 370                                            ssize_t len, const bfd_byte *data);
 371
 372 /* well-known interpreters */
 373 #define INTERP_CONSOLE          "console"
 374 #define INTERP_MI2             "mi2"
 375 #define INTERP_MI3             "mi3"
 376 #define INTERP_MI4             "mi4"
 377 #define INTERP_MI               "mi"
 378 #define INTERP_TUI              "tui"
 379 #define INTERP_INSIGHT          "insight"
 380
 381 #endif