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