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