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