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