kdbg/debugger.h

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