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   const char *name () const
  88   { return m_name; }
  89
  90   /* Notify the interpreter that the current inferior has stopped with signal
  91      SIG.  */
  92   virtual void on_signal_received (gdb_signal sig) {}
  93
  94   /* Notify the interpreter that the current inferior has exited with signal
  95      SIG. */
  96   virtual void on_signal_exited (gdb_signal sig) {}
  97
  98   /* Notify the interpreter that the current inferior has stopped normally.  */
  99   virtual void on_normal_stop (bpstat *bs, int print_frame) {}
 100
 101   /* Notify the interpreter that the current inferior has exited normally with
 102      status STATUS.  */
 103   virtual void on_exited (int status) {}
 104
 105   /* Notify the interpreter that the current inferior has stopped reverse
 106      execution because there is no more history.  */
 107   virtual void on_no_history () {}
 108
 109   /* Notify the interpreter that a synchronous command it started has
 110      finished.  */
 111   virtual void on_sync_execution_done () {}
 112
 113   /* Notify the interpreter that an error was caught while executing a
 114      command on this interpreter.  */
 115   virtual void on_command_error () {}
 116
 117   /* Notify the interpreter that the user focus has changed.  */
 118   virtual void on_user_selected_context_changed (user_selected_what selection)
 119     {}
 120
 121   /* Notify the interpreter that thread T has been created.  */
 122   virtual void on_new_thread (thread_info *t) {}
 123
 124   /* Notify the interpreter that thread T has exited.  */
 125   virtual void on_thread_exited (thread_info *,
 126                                  std::optional<ULONGEST> exit_code,
 127                                  int silent) {}
 128
 129   /* Notify the interpreter that inferior INF was added.  */
 130   virtual void on_inferior_added (inferior *inf) {}
 131
 132   /* Notify the interpreter that inferior INF was started or attached.  */
 133   virtual void on_inferior_appeared (inferior *inf) {}
 134
 135   /* Notify the interpreter that inferior INF exited or was detached.  */
 136   virtual void on_inferior_disappeared (inferior *inf) {}
 137
 138   /* Notify the interpreter that inferior INF was removed.  */
 139   virtual void on_inferior_removed (inferior *inf) {}
 140
 141   /* Notify the interpreter that the status of process record for INF
 142      changed.  */
 143   virtual void on_record_changed (inferior *inf, int started,
 144                                   const char *method, const char *format) {}
 145
 146   /* Notify the interpreter that the target was resumed.  */
 147   virtual void on_target_resumed (ptid_t ptid) {}
 148
 149   /* Notify the interpreter that solib SO has been loaded.  */
 150   virtual void on_solib_loaded (const solib &so) {}
 151
 152   /* Notify the interpreter that solib SO has been unloaded.  */
 153   virtual void on_solib_unloaded (const solib &so) {}
 154
 155   /* Notify the interpreter that a command it is executing is about to cause
 156      the inferior to proceed.  */
 157   virtual void on_about_to_proceed () {}
 158
 159   /* Notify the interpreter that the selected traceframe changed.  */
 160   virtual void on_traceframe_changed (int tfnum, int tpnum) {}
 161
 162   /* Notify the interpreter that trace state variable TSV was created.  */
 163   virtual void on_tsv_created (const trace_state_variable *tsv) {}
 164
 165   /* Notify the interpreter that trace state variable TSV was deleted.  */
 166   virtual void on_tsv_deleted (const trace_state_variable *tsv) {}
 167
 168   /* Notify the interpreter that trace state variable TSV was modified.  */
 169   virtual void on_tsv_modified (const trace_state_variable *tsv) {}
 170
 171   /* Notify the interpreter that breakpoint B was created.  */
 172   virtual void on_breakpoint_created (breakpoint *b) {}
 173
 174   /* Notify the interpreter that breakpoint B was deleted.  */
 175   virtual void on_breakpoint_deleted (breakpoint *b) {}
 176
 177   /* Notify the interpreter that breakpoint B was modified.  */
 178   virtual void on_breakpoint_modified (breakpoint *b) {}
 179
 180   /* Notify the interpreter that parameter PARAM changed to VALUE.  */
 181   virtual void on_param_changed (const char *param, const char *value) {}
 182
 183   /* Notify the interpreter that inferior INF's memory was changed.  */
 184   virtual void on_memory_changed (inferior *inf, CORE_ADDR addr, ssize_t len,
 185                                   const bfd_byte *data) {}
 186
 187 private:
 188   /* The memory for this is static, it comes from literal strings (e.g. "cli").  */
 189   const char *m_name;
 190
 191 public:
 192   /* Has the init method been run?  */
 193   bool inited = false;
 194 };
 195
 196 /* Look up the interpreter for NAME, creating one if none exists yet.
 197    If NAME is not a interpreter type previously registered with
 198    interp_factory_register, return NULL; otherwise return a pointer to
 199    the interpreter.  */
 200 extern struct interp *interp_lookup (struct ui *ui, const char *name);
 201
 202 /* Set the current UI's top level interpreter to the interpreter named
 203    NAME.  Throws an error if NAME is not a known interpreter or the
 204    interpreter fails to initialize.  */
 205 extern void set_top_level_interpreter (const char *name);
 206
 207 /* Temporarily set the current interpreter, and reset it on
 208    destruction.  */
 209 class scoped_restore_interp
 210 {
 211 public:
 212
 213   scoped_restore_interp (const char *name)
 214     : m_interp (set_interp (name))
 215   {
 216   }
 217
 218   ~scoped_restore_interp ()
 219   {
 220     set_interp (m_interp->name ());
 221   }
 222
 223   scoped_restore_interp (const scoped_restore_interp &) = delete;
 224   scoped_restore_interp &operator= (const scoped_restore_interp &) = delete;
 225
 226 private:
 227
 228   struct interp *set_interp (const char *name);
 229
 230   struct interp *m_interp;
 231 };
 232
 233 extern int current_interp_named_p (const char *name);
 234
 235 /* Call this function to give the current interpreter an opportunity
 236    to do any special handling of streams when logging is enabled or
 237    disabled.  LOGFILE is the stream for the log file when logging is
 238    starting and is NULL when logging is ending.  LOGGING_REDIRECT is
 239    the value of the "set logging redirect" setting.  If true, the
 240    interpreter should configure the output streams to send output only
 241    to the logfile.  If false, the interpreter should configure the
 242    output streams to send output to both the current output stream
 243    (i.e., the terminal) and the log file.  DEBUG_REDIRECT is same as
 244    LOGGING_REDIRECT, but for the value of "set logging debugredirect"
 245    instead.  */
 246 extern void current_interp_set_logging (ui_file_up logfile,
 247                                         bool logging_redirect,
 248                                         bool debug_redirect);
 249
 250 /* Returns the top-level interpreter.  */
 251 extern struct interp *top_level_interpreter (void);
 252
 253 /* Return the current UI's current interpreter.  */
 254 extern struct interp *current_interpreter (void);
 255
 256 extern struct interp *command_interp (void);
 257
 258 extern void clear_interpreter_hooks (void);
 259
 260 /* List the possible interpreters which could complete the given
 261    text.  */
 262 extern void interpreter_completer (struct cmd_list_element *ignore,
 263                                    completion_tracker &tracker,
 264                                    const char *text,
 265                                    const char *word);
 266
 267 /* Notify all interpreters that the current inferior has stopped with signal
 268    SIG.  */
 269 extern void interps_notify_signal_received (gdb_signal sig);
 270
 271 /* Notify all interpreters that the current inferior has exited with signal
 272    SIG.  */
 273 extern void interps_notify_signal_exited (gdb_signal sig);
 274
 275 /* Notify all interpreters that the current inferior has stopped normally.  */
 276 extern void interps_notify_normal_stop (bpstat *bs, int print_frame);
 277
 278 /* Notify all interpreters that the current inferior has stopped reverse
 279    execution because there is no more history.  */
 280 extern void interps_notify_no_history ();
 281
 282 /* Notify all interpreters that the current inferior has exited normally with
 283    status STATUS.  */
 284 extern void interps_notify_exited (int status);
 285
 286 /* Notify all interpreters that the user focus has changed.  */
 287 extern void interps_notify_user_selected_context_changed
 288   (user_selected_what selection);
 289
 290 /* Notify all interpreters that thread T has been created.  */
 291 extern void interps_notify_new_thread (thread_info *t);
 292
 293 /* Notify all interpreters that thread T has exited.  */
 294 extern void interps_notify_thread_exited (thread_info *t,
 295                                           std::optional<ULONGEST> exit_code,
 296                                           int silent);
 297
 298 /* Notify all interpreters that inferior INF was added.  */
 299 extern void interps_notify_inferior_added (inferior *inf);
 300
 301 /* Notify all interpreters that inferior INF was started or attached.  */
 302 extern void interps_notify_inferior_appeared (inferior *inf);
 303
 304 /* Notify all interpreters that inferior INF exited or was detached.  */
 305 extern void interps_notify_inferior_disappeared (inferior *inf);
 306
 307 /* Notify all interpreters that inferior INF was removed.  */
 308 extern void interps_notify_inferior_removed (inferior *inf);
 309
 310 /* Notify all interpreters that the status of process record for INF changed.
 311
 312    The process record is started if STARTED is true, and the process record is
 313    stopped if STARTED is false.
 314
 315    When STARTED is true, METHOD indicates the short name of the method used for
 316    recording.  If the method supports multiple formats, FORMAT indicates which
 317    one is being used, otherwise it is nullptr.  When STARTED is false, they are
 318    both nullptr.  */
 319 extern void interps_notify_record_changed (inferior *inf, int started,
 320                                            const char *method,
 321                                            const char *format);
 322
 323 /* Notify all interpreters that the target was resumed.  */
 324 extern void interps_notify_target_resumed (ptid_t ptid);
 325
 326 /* Notify all interpreters that solib SO has been loaded.  */
 327 extern void interps_notify_solib_loaded (const solib &so);
 328
 329 /* Notify all interpreters that solib SO has been unloaded.  */
 330 extern void interps_notify_solib_unloaded (const solib &so);
 331
 332 /* Notify all interpreters that the selected traceframe changed.
 333
 334    The trace frame is changed to TFNUM (e.g., by using the 'tfind' command).
 335    If TFNUM is negative, it means gdb resumed live debugging.  The number of
 336    the tracepoint associated with this traceframe is TPNUM.  */
 337 extern void interps_notify_traceframe_changed (int tfnum, int tpnum);
 338
 339 /* Notify all interpreters that trace state variable TSV was created.  */
 340 extern void interps_notify_tsv_created (const trace_state_variable *tsv);
 341
 342 /* Notify all interpreters that trace state variable TSV was deleted.
 343
 344    If TSV is nullptr, it means that all trace state variables were deleted.  */
 345 extern void interps_notify_tsv_deleted (const trace_state_variable *tsv);
 346
 347 /* Notify all interpreters that trace state variable TSV was modified.  */
 348 extern void interps_notify_tsv_modified (const trace_state_variable *tsv);
 349
 350 /* Notify all interpreters that breakpoint B was created.  */
 351 extern void interps_notify_breakpoint_created (breakpoint *b);
 352
 353 /* Notify all interpreters that breakpoint B was deleted.  */
 354 extern void interps_notify_breakpoint_deleted (breakpoint *b);
 355
 356 /* Notify all interpreters that breakpoint B was modified.  */
 357 extern void interps_notify_breakpoint_modified (breakpoint *b);
 358
 359 /* Notify all interpreters that parameter PARAM changed to VALUE.  */
 360 extern void interps_notify_param_changed (const char *param, const char *value);
 361
 362 /* Notify all interpreters that inferior INF's memory was changed.  */
 363 extern void interps_notify_memory_changed (inferior *inf, CORE_ADDR addr,
 364                                            ssize_t len, const bfd_byte *data);
 365
 366 /* well-known interpreters */
 367 #define INTERP_CONSOLE          "console"
 368 #define INTERP_MI2             "mi2"
 369 #define INTERP_MI3             "mi3"
 370 #define INTERP_MI4             "mi4"
 371 #define INTERP_MI               "mi"
 372 #define INTERP_TUI              "tui"
 373 #define INTERP_INSIGHT          "insight"
 374
 375 #endif