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