kdbg/debugger.h

   1 /*
   2  * Copyright Johannes Sixt
   3  * This file is licensed under the GNU General Public License Version 2.
   4  * See the file COPYING in the toplevel directory of the source directory.
   5  */
   6
   7 #ifndef DEBUGGER_H
   8 #define DEBUGGER_H
   9
  10 #include <qtimer.h>
  11 #include <qdict.h>
  12 #include <qstringlist.h>
  13 #include "envvar.h"
  14 #include "exprwnd.h"                    /* some compilers require this */
  15
  16 #ifdef HAVE_CONFIG_H
  17 #include "config.h"
  18 #endif
  19
  20 class ExprWnd;
  21 class VarTree;
  22 struct ExprValue;
  23 class ProgramTypeTable;
  24 class KTreeViewItem;
  25 class KConfig;
  26 class KConfigBase;
  27 class ProgramConfig;
  28 class QListBox;
  29 class RegisterInfo;
  30 class ThreadInfo;
  31 class DebuggerDriver;
  32 class CmdQueueItem;
  33 class Breakpoint;
  34 struct DisassembledCode;
  35 struct MemoryDump;
  36 struct DbgAddr;
  37 class KProcess;
  38
  39
  40 class KDebugger : public QObject
  41 {
  42     Q_OBJECT
  43 public:
  44     KDebugger(QWidget* parent,          /* will be used as the parent for dialogs */
  45               ExprWnd* localVars,
  46               ExprWnd* watchVars,
  47               QListBox* backtrace);
  48     ~KDebugger();
  49
  50     /**
  51      * This function starts to debug the specified executable using the
  52      * specified driver. If a program is currently being debugged, it is
  53      * terminated first. Ownership of driver is taken if and only if
  54      * true is returned.
  55      *
  56      * @return false if an error occurs.
  57      */
  58     bool debugProgram(const QString& executable,
  59                       DebuggerDriver* driver);
  60
  61     /**
  62      * Uses the specified core to debug the active program.
  63      * @param batch tells whether the core file was given on the
  64      * command line.
  65      */
  66     void useCoreFile(QString corefile, bool batch);
  67
  68     /**
  69      * Overrides the program argument in the per-program config
  70      * with a new value.
  71      */
  72     void overrideProgramArguments(const QString& args);
  73
  74
  75     /**
  76      * Uses the specified pid to attach to the active program.
  77      */
  78     void setAttachPid(const QString& pid);
  79
  80     /**
  81      * Attaches to the specified process and debugs it.
  82      */
  83     void attachProgram(const QString& pid);
  84
  85     /**
  86      * Returns the file name of the per-program config file for the
  87      * specified program.
  88      */
  89     static QString getConfigForExe(const QString& exe);
  90
  91     /**
  92      * The driver name entry in the per-program config file.
  93      */
  94     static const char DriverNameEntry[];
  95
  96 public slots:
  97     /**
  98      * Runs the program or continues it if it is stopped at a breakpoint.
  99      */
 100     void programRun();
 101
 102     /**
 103      * Restarts the debuggee.
 104      */
 105     void programRunAgain();
 106
 107     /**
 108      * Performs a single-step, possibly stepping into a function call.
 109      * If byInsn is true, a step by instruction is performed.
 110      */
 111     void programStep();
 112
 113     /**
 114      * Performs a single-step, stepping over a function call.
 115      * If byInsn is true, a step by instruction is performed.
 116      */
 117     void programNext();
 118
 119     /**
 120      * Performs a single-step by instruction, possibly stepping into a
 121      * function call.
 122      */
 123     void programStepi();
 124
 125     /**
 126      * Performs a single-step by instruction, stepping over a function
 127      * call.
 128      */
 129     void programNexti();
 130
 131     /**
 132      * Runs the program until it returns from the current function.
 133      */
 134     void programFinish();
 135
 136     /**
 137      * Kills the program (removes it from memory).
 138      */
 139     void programKill();
 140
 141     /**
 142      * Interrupts the program if it is currently running.
 143      */
 144     void programBreak();
 145
 146     /**
 147      * Moves the program counter to the specified line.
 148      * If an address is given, it is moved to the address.
 149      */
 150     void setProgramCounter(const QString&, int, const DbgAddr&);
 151
 152 public:
 153     /**
 154      * Queries the user for program arguments.
 155      */
 156     void programArgs(QWidget* parent);
 157
 158     /**
 159      * Queries the user for program settings: Debugger command, terminal
 160      * emulator.
 161      */
 162     void programSettings(QWidget* parent);
 163
 164     /**
 165      * Setup remote debugging device
 166      */
 167     void setRemoteDevice(const QString& remoteDevice) { m_remoteDevice = remoteDevice; }
 168
 169     /**
 170      * Run the debuggee until the specified line in the specified file is
 171      * reached.
 172      *
 173      * @return false if the command was not executed, e.g. because the
 174      * debuggee is running at the moment.
 175      */
 176     bool runUntil(const QString& fileName, int lineNo);
 177
 178     /**
 179      * Set a breakpoint.
 180      *
 181      * @param fileName The source file in which to set the breakpoint.
 182      * @param lineNo The zero-based line number.
 183      * @param address The exact address of the breakpoint.
 184      * @param temporary Specifies whether this is a temporary breakpoint
 185      * @return false if the command was not executed, e.g. because the
 186      * debuggee is running at the moment.
 187      */
 188     bool setBreakpoint(QString fileName, int lineNo,
 189                        const DbgAddr& address, bool temporary);
 190
 191     /**
 192      * Set a breakpoint.
 193      *
 194      * @param bp Describes the breakpoint.
 195      * @param queueOnly If false, the breakpoint is set using a high-priority command.
 196      */
 197     void setBreakpoint(Breakpoint* bp, bool queueOnly);
 198
 199     /**
 200      * Enable or disable a breakpoint at the specified location.
 201      *
 202      * @param fileName The source file in which the breakpoint is.
 203      * @param lineNo The zero-based line number.
 204      * @param address The exact address of the breakpoint.
 205      * @return false if the command was not executed, e.g. because the
 206      * debuggee is running at the moment.
 207      */
 208     bool enableDisableBreakpoint(QString fileName, int lineNo,
 209                                  const DbgAddr& address);
 210
 211     /**
 212      * Enables or disables the specified breakpoint.
 213      *
 214      * @return false if the command was not executed, e.g. because the
 215      * debuggee is running at the moment.
 216      */
 217     bool enableDisableBreakpoint(int id)
 218     { return enableDisableBreakpoint(breakpointById(id)); }
 219
 220     /**
 221      * Removes the specified breakpoint. Note that if bp is an orphaned
 222      * breakpoint, then bp is an invalid pointer if (and only if) this
 223      * function returns true.
 224      *
 225      * @return false if the command was not executed, e.g. because the
 226      * debuggee is running at the moment.
 227      */
 228     bool deleteBreakpoint(int id)
 229     { return deleteBreakpoint(breakpointById(id)); }
 230
 231     /**
 232      * Changes the specified breakpoint's condition and ignore count.
 233      *
 234      * @return false if the command was not executed, e.g. because the
 235      * debuggee is running at the moment.
 236      */
 237     bool conditionalBreakpoint(int id,
 238                                const QString& condition,
 239                                int ignoreCount)
 240     { return conditionalBreakpoint(breakpointById(id), condition, ignoreCount); }
 241
 242     /**
 243      * Tells whether one of the single stepping commands can be invoked
 244      * (step, next, finish, until, also run).
 245      */
 246     bool canSingleStep();
 247
 248     /**
 249      * Tells whether a breakpoints can be set, deleted, enabled, or disabled.
 250      */
 251     bool canChangeBreakpoints();
 252
 253     /**
 254      * Tells whether a the program is loaded, but not active.
 255      */
 256     bool canStart();
 257
 258     /**
 259      * Add a watch expression.
 260      */
 261     void addWatch(const QString& expr);
 262
 263     /**
 264      * Retrieves the current status message.
 265      */
 266     const QString& statusMessage() const { return m_statusMessage; }
 267
 268     /**
 269      * Is the debugger ready to receive another high-priority command?
 270      */
 271     bool isReady() const;
 272
 273     /**
 274      * Is the debuggee running (not just active)?
 275      */
 276     bool isProgramRunning() { return m_haveExecutable && m_programRunning; }
 277
 278     /**
 279      * Do we have an executable set?
 280      */
 281     bool haveExecutable() { return m_haveExecutable; }
 282
 283     /**
 284      * Is the debuggee active, i.e. was it started by the debugger?
 285      */
 286     bool isProgramActive() { return m_programActive; }
 287
 288     /**
 289      * Is the debugger driver idle?
 290      */
 291     bool isIdle() const;
 292
 293     /* The list of breakpoints. */
 294     typedef std::list<Breakpoint>::const_iterator BrkptROIterator;
 295     BrkptROIterator breakpointsBegin() const { return m_brkpts.begin(); }
 296     BrkptROIterator breakpointsEnd() const { return m_brkpts.end(); }
 297
 298     const QString& executable() const { return m_executable; }
 299
 300     /**
 301      * Terminal emulation level.
 302      */
 303     enum TTYLevel {
 304         ttyNone = 0,                    /* ignore output, input triggers EOF */
 305         ttySimpleOutputOnly = 1,        /* minmal output emulation, input triggers EOF */
 306         ttyFull = 7                     /* program needs full emulation */
 307     };
 308
 309     /**
 310      * Returns the level of terminal emulation requested by the inferior.
 311      */
 312     TTYLevel ttyLevel() const { return m_ttyLevel; }
 313
 314     /** Sets the terminal that is to be used by the debugger. */
 315     void setTerminal(const QString& term) { m_inferiorTerminal = term; }
 316
 317     /** Returns the debugger driver. */
 318     DebuggerDriver* driver() { return m_d; }
 319
 320     /** Returns the pid that the debugger is currently attached to. */
 321     const QString& attachedPid() const { return m_attachedPid; }
 322
 323     /**
 324      * The memory at that the expression evaluates to is watched. Can be
 325      * empty. Triggers a redisplay even if the expression did not change.
 326      */
 327     void setMemoryExpression(const QString& memexpr);
 328
 329     /**
 330      * Sets how the watched memory location is displayed.
 331      * Call setMemoryExpression() to force a redisplay.
 332      */
 333     void setMemoryFormat(unsigned format) { m_memoryFormat = format; }
 334
 335     // settings
 336     void saveSettings(KConfig*);
 337     void restoreSettings(KConfig*);
 338
 339 protected:
 340     QString m_inferiorTerminal;
 341     QString m_debuggerCmd;              /* per-program setting */
 342     TTYLevel m_ttyLevel;                /* level of terminal emulation */
 343     bool startDriver();
 344     void stopDriver();
 345     void writeCommand();
 346
 347     QStringList m_watchEvalExpr;        /* exprs to evaluate for watch window */
 348     std::list<Breakpoint> m_brkpts;
 349     QString m_memoryExpression;         /* memory location to watch */
 350     unsigned m_memoryFormat;            /* how that output should look */
 351
 352 protected slots:
 353     void parse(CmdQueueItem* cmd, const char* output);
 354 protected:
 355     void handleRunCommands(const char* output);
 356     void updateAllExprs();
 357     void updateProgEnvironment(const QString& args, const QString& wd,
 358                                const QDict<EnvVar>& newVars,
 359                                const QStringList& newOptions);
 360     void parseLocals(const char* output, QList<ExprValue>& newVars);
 361     void handleLocals(const char* output);
 362     bool handlePrint(CmdQueueItem* cmd, const char* output);
 363     bool handlePrintDeref(CmdQueueItem* cmd, const char* output);
 364     void handleBacktrace(const char* output);
 365     void handleFrameChange(const char* output);
 366     void handleFindType(CmdQueueItem* cmd, const char* output);
 367     void handlePrintStruct(CmdQueueItem* cmd, const char* output);
 368     void handleSharedLibs(const char* output);
 369     void handleRegisters(const char* output);
 370     void handleMemoryDump(const char* output);
 371     void handleInfoLine(CmdQueueItem* cmd, const char* output);
 372     void handleDisassemble(CmdQueueItem* cmd, const char* output);
 373     void handleThreadList(const char* output);
 374     void handleSetPC(const char* output);
 375     void handleSetVariable(CmdQueueItem* cmd, const char* output);
 376     void evalExpressions();
 377     void evalInitialStructExpression(VarTree* var, ExprWnd* wnd, bool immediate);
 378     void evalStructExpression(VarTree* var, ExprWnd* wnd, bool immediate);
 379     void dereferencePointer(ExprWnd* wnd, VarTree* var, bool immediate);
 380     void determineType(ExprWnd* wnd, VarTree* var);
 381     void queueMemoryDump(bool immediate);
 382     CmdQueueItem* loadCoreFile();
 383     void openProgramConfig(const QString& name);
 384
 385     typedef std::list<Breakpoint>::iterator BrkptIterator;
 386     BrkptIterator breakpointByFilePos(QString file, int lineNo,
 387                                     const DbgAddr& address);
 388     BrkptIterator breakpointById(int id);
 389     CmdQueueItem* executeBreakpoint(const Breakpoint* bp, bool queueOnly);
 390     void newBreakpoint(CmdQueueItem* cmd, const char* output);
 391     void updateBreakList(const char* output);
 392     bool stopMayChangeBreakList() const;
 393     void saveBreakpoints(ProgramConfig* config);
 394     void restoreBreakpoints(ProgramConfig* config);
 395     bool enableDisableBreakpoint(BrkptIterator bp);
 396     bool deleteBreakpoint(BrkptIterator bp);
 397     bool conditionalBreakpoint(BrkptIterator bp,
 398                                const QString& condition,
 399                                int ignoreCount);
 400
 401     bool m_haveExecutable;              /* has an executable been specified */
 402     bool m_programActive;               /* is the program active (possibly halting in a brkpt)? */
 403     bool m_programRunning;              /* is the program executing (not stopped)? */
 404     bool m_sharedLibsListed;            /* do we know the shared libraries loaded by the prog? */
 405     QString m_executable;
 406     QString m_corefile;
 407     QString m_attachedPid;              /* user input of attaching to pid */
 408     QString m_programArgs;
 409     QString m_remoteDevice;
 410     QString m_programWD;                /* working directory of gdb */
 411     QDict<EnvVar> m_envVars;            /* environment variables set by user */
 412     QStringList m_boolOptions;          /* boolean options */
 413     QStrList m_sharedLibs;              /* shared libraries used by program */
 414     ProgramTypeTable* m_typeTable;      /* known types used by the program */
 415     ProgramConfig* m_programConfig;     /* program-specific settings (brkpts etc) */
 416     void saveProgramSettings();
 417     void restoreProgramSettings();
 418     QString readDebuggerCmd();
 419
 420     // debugger process
 421     DebuggerDriver* m_d;
 422     bool m_explicitKill;                /* whether we are killing gdb ourselves */
 423
 424     QString m_statusMessage;
 425
 426 protected slots:
 427     void gdbExited(KProcess*);
 428     void slotInferiorRunning();
 429     void backgroundUpdate();
 430     void gotoFrame(int);
 431     void slotExpanding(QListViewItem*);
 432     void slotDeleteWatch();
 433     void slotValuePopup(const QString&);
 434     void slotDisassemble(const QString&, int);
 435     void slotValueEdited(VarTree*, const QString&);
 436 public slots:
 437     void setThread(int);
 438     void shutdown();
 439
 440 signals:
 441     /**
 442      * This signal is emitted before the debugger is started. The slot is
 443      * supposed to set up m_inferiorTerminal.
 444      */
 445     void debuggerStarting();
 446
 447     /**
 448      * This signal is emitted whenever a part of the debugger needs to
 449      * highlight the specfied source code line (e.g. when the program
 450      * stops).
 451      *
 452      * @param file specifies the file; this is not necessarily a full path
 453      * name, and if it is relative, you won't know relative to what, you
 454      * can only guess.
 455      * @param lineNo specifies the line number (0-based!) (this may be
 456      * negative, in which case the file should be activated, but the line
 457      * should NOT be changed).
 458      * @param address specifies the exact address of the PC or is empty.
 459      */
 460     void activateFileLine(const QString& file, int lineNo, const DbgAddr& address);
 461
 462     /**
 463      * This signal indicates that the program counter has changed.
 464      *
 465      * @param filename specifies the filename where the program stopped
 466      * @param lineNo specifies the line number (zero-based); it can be -1
 467      * if it is unknown
 468      * @param address specifies the address that the instruction pointer
 469      * points to.
 470      * @param frameNo specifies the frame number: 0 is the innermost frame,
 471      * positive numbers are frames somewhere up the stack (indicates points
 472      * where a function was called); the latter cases should be indicated
 473      * differently in the source window.
 474      */
 475     void updatePC(const QString& filename, int lineNo,
 476                   const DbgAddr& address, int frameNo);
 477
 478     /**
 479      * This signal is emitted when gdb detects that the executable has been
 480      * updated, e.g. recompiled. (You usually need not handle this signal
 481      * if you are the editor which changed the executable.)
 482      */
 483     void executableUpdated();
 484
 485     /**
 486      * Indicates that a new status message is available.
 487      */
 488     void updateStatusMessage();
 489
 490     /**
 491      * Indicates that the internal state of the debugger has changed, and
 492      * that this will very likely have an impact on the UI.
 493      */
 494     void updateUI();
 495
 496     /**
 497      * Indicates that the list of breakpoints has possibly changed.
 498      */
 499     void breakpointsChanged();
 500
 501     /**
 502      * Indicates that the register values have possibly changed.
 503      */
 504     void registersChanged(QList<RegisterInfo>&);
 505
 506     /**
 507      * Indicates that the list of threads has possibly changed.
 508      */
 509     void threadsChanged(QList<ThreadInfo>&);
 510
 511     /**
 512      * Indicates that the value for a value popup is ready.
 513      */
 514     void valuePopup(const QString&);
 515
 516     /**
 517      * Provides the disassembled code of the location given by file and
 518      * line number (zero-based).
 519      */
 520     void disassembled(const QString& file, int line, const QList<DisassembledCode>& code);
 521
 522     /**
 523      * Indicates that the program has stopped for any reason: by a
 524      * breakpoint, by a signal that the debugger driver caught, by a single
 525      * step instruction.
 526      */
 527     void programStopped();
 528
 529     /**
 530      * Indicates that a new memory dump output is ready.
 531      * @param msg is an error message or empty
 532      * @param memdump is the memory dump
 533      */
 534     void memoryDumpChanged(const QString&, QList<MemoryDump>&);
 535
 536     /**
 537      * Gives other objects a chance to save program specific settings.
 538      */
 539     void saveProgramSpecific(KConfigBase* config);
 540
 541     /**
 542      * Gives other objects a chance to restore program specific settings.
 543      */
 544     void restoreProgramSpecific(KConfigBase* config);
 545
 546 protected:
 547     ExprWnd& m_localVariables;
 548     ExprWnd& m_watchVariables;
 549     QListBox& m_btWindow;
 550
 551     // implementation helpers
 552 protected:
 553     QWidget* parentWidget() { return static_cast<QWidget*>(parent()); }
 554 };
 555
 556 #endif // DEBUGGER_H