kdbg/dbgdriver.h

   1 // $Id$
   2
   3 // Copyright by Johannes Sixt
   4 // This file is under GPL, the GNU General Public Licence
   5
   6 #ifndef DBGDRIVER_H
   7 #define DBGDRIVER_H
   8
   9 #include <qptrqueue.h>
  10 #include <qptrlist.h>
  11 #include <qfile.h>
  12 #include <qregexp.h>
  13 #include <kprocess.h>
  14
  15
  16 class VarTree;
  17 class ExprValue;
  18 class ExprWnd;
  19 class KDebugger;
  20 class QStrList;
  21 class QStringList;
  22
  23
  24 /**
  25  * A type representing an address.
  26  */
  27 struct DbgAddr
  28 {
  29     QString a;
  30     QString fnoffs;
  31     DbgAddr() { }
  32     DbgAddr(const QString& aa);
  33     DbgAddr(const DbgAddr& src) : a(src.a), fnoffs(src.fnoffs) { }
  34     void operator=(const QString& aa);
  35     void operator=(const DbgAddr& src) { a = src.a; fnoffs = src.fnoffs; }
  36     QString asString() const;
  37     bool isEmpty() const { return a.isEmpty(); }
  38 protected:
  39     void cleanAddr();
  40 };
  41 bool operator==(const DbgAddr& a1, const DbgAddr& a2);
  42 bool operator>(const DbgAddr& a1, const DbgAddr& a2);
  43
  44
  45 enum DbgCommand {
  46         DCinitialize,
  47         DCtty,
  48         DCexecutable,
  49         DCtargetremote,
  50         DCcorefile,
  51         DCattach,
  52         DCinfolinemain,
  53         DCinfolocals,
  54         DCinforegisters,
  55         DCexamine,
  56         DCinfoline,
  57         DCdisassemble,
  58         DCsetargs,
  59         DCsetenv,
  60         DCunsetenv,
  61         DCsetoption,                    /* debugger options */
  62         DCcd,
  63         DCbt,
  64         DCrun,
  65         DCcont,
  66         DCstep,
  67         DCstepi,
  68         DCnext,
  69         DCnexti,
  70         DCfinish,
  71         DCuntil,                        /* line number is zero-based! */
  72         DCkill,
  73         DCbreaktext,
  74         DCbreakline,                    /* line number is zero-based! */
  75         DCtbreakline,                   /* line number is zero-based! */
  76         DCbreakaddr,
  77         DCtbreakaddr,
  78         DCwatchpoint,
  79         DCdelete,
  80         DCenable,
  81         DCdisable,
  82         DCprint,
  83         DCprintDeref,
  84         DCprintStruct,
  85         DCprintQStringStruct,
  86         DCframe,
  87         DCfindType,
  88         DCinfosharedlib,
  89         DCthread,
  90         DCinfothreads,
  91         DCinfobreak,
  92         DCcondition,
  93         DCsetpc,
  94         DCignore,
  95         DCprintWChar,
  96         DCsetvariable
  97 };
  98
  99 enum RunDevNull {
 100     RDNstdin = 0x1,                     /* redirect stdin to /dev/null */
 101     RDNstdout = 0x2,                    /* redirect stdout to /dev/null */
 102     RDNstderr = 0x4                     /* redirect stderr to /dev/null */
 103 };
 104
 105 /**
 106  * How the memory dump is formated. The lowest 4 bits define the size of
 107  * the entities. The higher bits define how these are formatted. Note that
 108  * not all combinations make sense.
 109  */
 110 enum MemoryDumpType {
 111     // sizes
 112     MDTbyte = 0x1,
 113     MDThalfword = 0x2,
 114     MDTword = 0x3,
 115     MDTgiantword = 0x4,
 116     MDTsizemask = 0xf,
 117     // formats
 118     MDThex = 0x10,
 119     MDTsigned = 0x20,
 120     MDTunsigned = 0x30,
 121     MDToctal = 0x40,
 122     MDTbinary = 0x50,
 123     MDTaddress = 0x60,
 124     MDTchar = 0x70,
 125     MDTfloat = 0x80,
 126     MDTstring = 0x90,
 127     MDTinsn = 0xa0,
 128     MDTformatmask = 0xf0
 129 };
 130
 131 struct Breakpoint;
 132
 133 /**
 134  * Debugger commands are placed in a queue. Only one command at a time is
 135  * sent down to the debugger. All other commands in the queue are retained
 136  * until the sent command has been processed by gdb. The debugger tells us
 137  * that it's done with the command by sending the prompt. The output of the
 138  * debugger is parsed at that time. Then, if more commands are in the
 139  * queue, the next one is sent to the debugger.
 140  */
 141 struct CmdQueueItem
 142 {
 143     DbgCommand m_cmd;
 144     QString m_cmdString;
 145     bool m_committed;                   /* just a debugging aid */
 146     // remember which expression when printing an expression
 147     VarTree* m_expr;
 148     ExprWnd* m_exprWnd;
 149     // remember file position
 150     QString m_fileName;
 151     int m_lineNo;
 152     // the breakpoint info
 153     Breakpoint* m_brkpt;
 154     // whether command was emitted due to direct user request (only set when relevant)
 155     bool m_byUser;
 156
 157     CmdQueueItem(DbgCommand cmd, const QString& str) :
 158         m_cmd(cmd),
 159         m_cmdString(str),
 160         m_committed(false),
 161         m_expr(0),
 162         m_exprWnd(0),
 163         m_lineNo(0),
 164         m_brkpt(0),
 165         m_byUser(false)
 166     { }
 167 };
 168
 169 /**
 170  * The information about a breakpoint that is parsed from the list of
 171  * breakpoints.
 172  */
 173 struct Breakpoint
 174 {
 175     int id;                             /* gdb's number */
 176     enum Type {
 177         breakpoint, watchpoint
 178     } type;
 179     bool temporary;
 180     bool enabled;
 181     QString location;
 182     QString text;                       /* text if set using DCbreaktext */
 183     DbgAddr address;                    /* exact address of breakpoint */
 184     QString condition;                  /* condition as printed by gdb */
 185     int ignoreCount;                    /* ignore next that may hits */
 186     int hitCount;                       /* as reported by gdb */
 187     // the following items repeat the location, but in a better usable way
 188     QString fileName;
 189     int lineNo;                         /* zero-based line number */
 190     Breakpoint();
 191     bool isOrphaned() const { return id < 0; }
 192 };
 193
 194 /**
 195  * Information about a stack frame.
 196  */
 197 struct FrameInfo
 198 {
 199     QString fileName;
 200     int lineNo;                         /* zero-based line number */
 201     DbgAddr address;                    /* exact address of PC */
 202 };
 203
 204 /**
 205  * The information about a stack frame as parsed from the backtrace.
 206  */
 207 struct StackFrame : FrameInfo
 208 {
 209     int frameNo;
 210     ExprValue* var;                     /* more information if non-zero */
 211     StackFrame() : var(0) { }
 212     ~StackFrame();
 213 };
 214
 215 /**
 216  * The information about a thread as parsed from the threads list.
 217  */
 218 struct ThreadInfo : FrameInfo
 219 {
 220     int id;                             /* gdb's number */
 221     QString threadName;                 /* the SYSTAG */
 222     QString function;                   /* where thread is halted */
 223     bool hasFocus;                      /* the thread whose stack we are watching */
 224 };
 225
 226 /**
 227  * Register information
 228  */
 229 struct RegisterInfo
 230 {
 231     QString regName;
 232     QString rawValue;
 233     QString cookedValue;                /* may be empty */
 234     QString type;                       /* of vector register if not empty */
 235 };
 236
 237 /**
 238  * Disassembled code
 239  */
 240 struct DisassembledCode
 241 {
 242     DbgAddr address;
 243     QString code;
 244 };
 245
 246 /**
 247  * Memory contents
 248  */
 249 struct MemoryDump
 250 {
 251     DbgAddr address;
 252     QString dump;
 253 };
 254
 255 /**
 256  * This is an abstract base class for debugger process.
 257  *
 258  * This class represents the debugger program. It provides the low-level
 259  * interface to the commandline debugger. As such it implements the
 260  * commands and parses the output.
 261  */
 262 class DebuggerDriver : public KProcess
 263 {
 264     Q_OBJECT
 265 public:
 266     DebuggerDriver();
 267     virtual ~DebuggerDriver() = 0;
 268
 269     virtual QString driverName() const = 0;
 270     /**
 271      * Returns the default command string to invoke the debugger driver.
 272      */
 273     virtual QString defaultInvocation() const = 0;
 274
 275     /**
 276      * Returns a list of options that can be  turned on and off.
 277      */
 278     virtual QStringList boolOptionList() const = 0;
 279
 280     virtual bool startup(QString cmdStr);
 281     void setLogFileName(const QString& fname) { m_logFileName = fname; }
 282
 283 protected:
 284     QString m_runCmd;
 285
 286     enum DebuggerState {
 287         DSidle,                         /* gdb waits for input */
 288         DSinterrupted,                  /* a command was interrupted */
 289         DSrunningLow,                   /* gdb is running a low-priority command */
 290         DSrunning,                      /* gdb waits for program */
 291         DScommandSent,                  /* command has been sent, we wait for wroteStdin signal */
 292         DScommandSentLow                /* low-prioritycommand has been sent */
 293     };
 294     DebuggerState m_state;
 295
 296 public:
 297     bool isIdle() const { return m_state == DSidle; }
 298     /**
 299      * Tells whether a high prority command would be executed immediately.
 300      */
 301     bool canExecuteImmediately() const { return m_hipriCmdQueue.isEmpty(); }
 302
 303 protected:
 304     char* m_output;                     /* normal gdb output */
 305     size_t m_outputLen;                 /* amount of data so far accumulated in m_output */
 306     size_t m_outputAlloc;               /* space available in m_output */
 307     typedef QCString DelayedStr;
 308     QQueue<DelayedStr> m_delayedOutput; /* output colleced while we have receivedOutput */
 309                                         /* but before signal wroteStdin arrived */
 310
 311 public:
 312     /**
 313      * Enqueues a high-priority command. High-priority commands are
 314      * executed before any low-priority commands. No user interaction is
 315      * possible as long as there is a high-priority command in the queue.
 316      */
 317     virtual CmdQueueItem* executeCmd(DbgCommand,
 318                                      bool clearLow = false) = 0;
 319     virtual CmdQueueItem* executeCmd(DbgCommand, QString strArg,
 320                                      bool clearLow = false) = 0;
 321     virtual CmdQueueItem* executeCmd(DbgCommand, int intArg,
 322                                      bool clearLow = false) = 0;
 323     virtual CmdQueueItem* executeCmd(DbgCommand, QString strArg, int intArg,
 324                                      bool clearLow = false) = 0;
 325     virtual CmdQueueItem* executeCmd(DbgCommand, QString strArg1, QString strArg2,
 326                                      bool clearLow = false) = 0;
 327     virtual CmdQueueItem* executeCmd(DbgCommand, int intArg1, int intArg2,
 328                                      bool clearLow = false) = 0;
 329
 330     enum QueueMode {
 331         QMnormal,                       /* queues the command last */
 332         QMoverride,                     /* removes an already queued command */
 333         QMoverrideMoreEqual             /* ditto, also puts the command first in the queue */
 334     };
 335
 336     /**
 337      * Enqueues a low-priority command. Low-priority commands are executed
 338      * after any high-priority commands.
 339      */
 340     virtual CmdQueueItem* queueCmd(DbgCommand,
 341                                    QueueMode mode) = 0;
 342     virtual CmdQueueItem* queueCmd(DbgCommand, QString strArg,
 343                                    QueueMode mode) = 0;
 344     virtual CmdQueueItem* queueCmd(DbgCommand, int intArg,
 345                                    QueueMode mode) = 0;
 346     virtual CmdQueueItem* queueCmd(DbgCommand, QString strArg, int intArg,
 347                                    QueueMode mode) = 0;
 348     virtual CmdQueueItem* queueCmd(DbgCommand, QString strArg1, QString strArg2,
 349                                    QueueMode mode) = 0;
 350
 351     /**
 352      * Flushes the command queues.
 353      * @param hipriOnly if true, only the high priority queue is flushed.
 354      */
 355     virtual void flushCommands(bool hipriOnly = false);
 356
 357     /**
 358      * Terminates the debugger process.
 359      */
 360     virtual void terminate() = 0;
 361
 362     /**
 363      * Terminates the debugger process, but also detaches any program that
 364      * it has been attached to.
 365      */
 366     virtual void detachAndTerminate() = 0;
 367
 368     /**
 369      * Interrupts the debuggee.
 370      */
 371     virtual void interruptInferior() = 0;
 372
 373     /**
 374      * Specifies the command that prints the QString data.
 375      */
 376     virtual void setPrintQStringDataCmd(const char* cmd) = 0;
 377
 378     /**
 379      * Parses the output as an array of QChars.
 380      */
 381     virtual ExprValue* parseQCharArray(const char* output, bool wantErrorValue, bool qt3like) = 0;
 382
 383     /**
 384      * Parses a back-trace (the output of the DCbt command).
 385      */
 386     virtual void parseBackTrace(const char* output, QList<StackFrame>& stack) = 0;
 387
 388     /**
 389      * Parses the output of the DCframe command;
 390      * @param frameNo Returns the frame number.
 391      * @param file Returns the source file name.
 392      * @param lineNo The zero-based line number.
 393      * @param address Returns the exact address.
 394      * @return false if the frame could not be parsed successfully. The
 395      * output values are undefined in this case.
 396      */
 397     virtual bool parseFrameChange(const char* output, int& frameNo,
 398                                   QString& file, int& lineNo, DbgAddr& address) = 0;
 399
 400     /**
 401      * Parses a list of breakpoints.
 402      * @param output The output of the debugger.
 403      * @param brks The list of new #Breakpoint objects. The list
 404      * must initially be empty.
 405      * @return False if there was an error before the first breakpoint
 406      * was found. Even if true is returned, #brks may be empty.
 407      */
 408     virtual bool parseBreakList(const char* output, QList<Breakpoint>& brks) = 0;
 409
 410     /**
 411      * Parses a list of threads.
 412      * @param output The output of the debugger.
 413      * @param threads The list of new #ThreadInfo objects. The list
 414      * must initially be empty.
 415      * @return False if there was an error before the first thread entry
 416      * was found. Even if true is returned, #threads may be empty.
 417      */
 418     virtual bool parseThreadList(const char* output, QList<ThreadInfo>& threads) = 0;
 419
 420     /**
 421      * Parses the output when the program stops to see whether this it
 422      * stopped due to a breakpoint.
 423      * @param output The output of the debugger.
 424      * @param id Returns the breakpoint id.
 425      * @param file Returns the file name in which the breakpoint is.
 426      * @param lineNo Returns the zero-based line number of the breakpoint.
 427      * @param address Returns the address of the breakpoint.
 428      * @return False if there was no breakpoint.
 429      */
 430     virtual bool parseBreakpoint(const char* output, int& id,
 431                                  QString& file, int& lineNo, QString& address) = 0;
 432
 433     /**
 434      * Parses the output of the DCinfolocals command.
 435      * @param output The output of the debugger.
 436      * @param newVars Receives the parsed variable values. The values are
 437      * simply append()ed to the supplied list.
 438      */
 439     virtual void parseLocals(const char* output, QList<ExprValue>& newVars) = 0;
 440
 441     /**
 442      * Parses the output of a DCprint or DCprintStruct command.
 443      * @param output The output of the debugger.
 444      * @param wantErrorValue Specifies whether the error message should be
 445      * provided as the value of a NKplain variable. If this is false,
 446      * 0 is returned if the printed value is an error message.
 447      * @return the parsed value. It is 0 if there was a parse error
 448      * or if the output is an error message and #wantErrorValue
 449      * is \c false. The returned object's text() is undefined.
 450      */
 451     virtual ExprValue* parsePrintExpr(const char* output, bool wantErrorValue) = 0;
 452
 453     /**
 454      * Parses the output of the DCcd command.
 455      * @return false if the message is an error message.
 456      */
 457     virtual bool parseChangeWD(const char* output, QString& message) = 0;
 458
 459     /**
 460      * Parses the output of the DCexecutable command.
 461      * @return false if an error occured.
 462      */
 463     virtual bool parseChangeExecutable(const char* output, QString& message) = 0;
 464
 465     /**
 466      * Parses the output of the DCcorefile command.
 467      * @return false if the core file was not loaded successfully.
 468      */
 469     virtual bool parseCoreFile(const char* output) = 0;
 470
 471     enum StopFlags {
 472         SFrefreshSource = 1,            /* refresh of source code is needed */
 473         SFrefreshBreak = 2,             /* refresh breakpoints */
 474         SFrefreshThreads = 4,           /* refresh thread list */
 475         SFprogramActive = 128           /* program remains active */
 476     };
 477     /**
 478      * Parses the output of commands that execute (a piece of) the program.
 479      * @return The inclusive OR of zero or more of the StopFlags.
 480      */
 481     virtual uint parseProgramStopped(const char* output, QString& message) = 0;
 482
 483     /**
 484      * Parses the output of the DCsharedlibs command.
 485      */
 486     virtual void parseSharedLibs(const char* output, QStrList& shlibs) = 0;
 487
 488     /**
 489      * Parses the output of the DCfindType command.
 490      * @return true if a type was found.
 491      */
 492     virtual bool parseFindType(const char* output, QString& type) = 0;
 493
 494     /**
 495      * Parses the output of the DCinforegisters command.
 496      */
 497     virtual void parseRegisters(const char* output, QList<RegisterInfo>& regs) = 0;
 498
 499     /**
 500      * Parses the output of the DCinfoline command. Returns false if the
 501      * two addresses could not be found.
 502      */
 503     virtual bool parseInfoLine(const char* output,
 504                                QString& addrFrom, QString& addrTo) = 0;
 505
 506     /**
 507      * Parses the ouput of the DCdisassemble command.
 508      */
 509     virtual void parseDisassemble(const char* output, QList<DisassembledCode>& code) = 0;
 510
 511     /**
 512      * Parses a memory dump. Returns an empty string if no error was found;
 513      * otherwise it contains an error message.
 514      */
 515     virtual QString parseMemoryDump(const char* output, QList<MemoryDump>& memdump) = 0;
 516
 517     /**
 518      * Parses the output of the DCsetvariable command. Returns an empty
 519      * string if no error was found; otherwise it contains an error
 520      * message.
 521      */
 522     virtual QString parseSetVariable(const char* output) = 0;
 523
 524     /**
 525      * Returns a value that the user can edit.
 526      */
 527     virtual QString editableValue(VarTree* value);
 528
 529 protected:
 530     /** Removes all commands from the low-priority queue. */
 531     void flushLoPriQueue();
 532     /** Removes all commands from  the high-priority queue. */
 533     void flushHiPriQueue();
 534
 535     QQueue<CmdQueueItem> m_hipriCmdQueue;
 536     QList<CmdQueueItem> m_lopriCmdQueue;
 537     /**
 538      * The active command is kept separately from other pending commands.
 539      */
 540     CmdQueueItem* m_activeCmd;
 541     /**
 542      * Helper function that queues the given command string in the
 543      * low-priority queue.
 544      */
 545     CmdQueueItem* queueCmdString(DbgCommand cmd, QString cmdString,
 546                                  QueueMode mode);
 547     /**
 548      * Helper function that queues the given command string in the
 549      * high-priority queue.
 550      */
 551     CmdQueueItem* executeCmdString(DbgCommand cmd, QString cmdString,
 552                                    bool clearLow);
 553     void writeCommand();
 554     virtual void commandFinished(CmdQueueItem* cmd) = 0;
 555
 556 protected:
 557     /** @internal */
 558     virtual int commSetupDoneC();
 559
 560     char m_prompt[10];
 561     size_t m_promptMinLen;
 562     char m_promptLastChar;
 563     QRegExp m_promptRE;
 564
 565     // log file
 566     QString m_logFileName;
 567     QFile m_logFile;
 568
 569 public slots:
 570     void dequeueCmdByVar(VarTree* var);
 571
 572 protected slots:
 573     virtual void slotReceiveOutput(KProcess*, char* buffer, int buflen);
 574     virtual void slotCommandRead(KProcess*);
 575     virtual void slotExited(KProcess*);
 576
 577 signals:
 578     /**
 579      * This signal is emitted when the output of a command has been fully
 580      * collected and is ready to be interpreted.
 581      */
 582     void commandReceived(CmdQueueItem* cmd, const char* output);
 583
 584     /**
 585      * This signal is emitted when the debugger recognizes that a specific
 586      * location in a file ought to be displayed.
 587      *
 588      * Gdb's --fullname option supports this for the step, next, frame, and
 589      * run commands (and possibly others).
 590      *
 591      * @param file specifies the file; this is not necessarily a full path
 592      * name, and if it is relative, you won't know relative to what, you
 593      * can only guess.
 594      * @param lineNo specifies the line number (0-based!) (this may be
 595      * negative, in which case the file should be activated, but the line
 596      * should NOT be changed).
 597      * @param address specifies the exact address of the PC or is empty.
 598      */
 599     void activateFileLine(const QString& file, int lineNo, const DbgAddr& address);
 600
 601     /**
 602      * This signal is emitted when a command that starts the inferior has
 603      * been submitted to the debugger.
 604      */
 605     void inferiorRunning();
 606
 607     /**
 608      * This signal is emitted when all output from the debugger has been
 609      * consumed and no more commands are in the queues.
 610      */
 611     void enterIdleState();
 612 };
 613
 614 #endif // DBGDRIVER_H