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