/*
$Header: d:/cvsroot/tads/TADS2/DBG.H,v 1.3 1999/07/11 00:46:29 MJRoberts Exp $
*/

/* 
 *   Copyright (c) 1992, 2002 Michael J. Roberts.  All Rights Reserved.
 *   
 *   Please see the accompanying license file, LICENSE.TXT, for information
 *   on using and copying this software.  
 */
/*
Name
  dbg.h - debug interface
Function
  Debugger interface definitions
Notes
  The Debugger implementation is split into two parts:  the "engine",
  which implements the parts of the debugger that are independent of
  user interface; and the UI.  The UI is in a separate module so that
  several user interfaces can be provided, and a particular one chosen
  at link time.  The UI section should contain nothing that is generic,
  but only the parts specific to that user interface.
Modified
  04/11/99 CNebel        - Move extern C.
  03/28/92 MJRoberts     - creation
*/

#ifndef DBG_INCLUDED
#define DBG_INCLUDED

#ifndef OBJ_INCLUDED
#include "obj.h"
#endif
#ifndef PRP_INCLUDED
#include "prp.h"
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* forward declarations */
struct bifcxdef;
struct toksdef;
struct toktdef;
struct tokcxdef;

/* stack frame record */
struct dbgfdef
{
    struct runsdef *dbgfbp;                        /* base pointer of frame */
    objnum  dbgfself;             /* 'self' object (MCMONINV for functions) */
    objnum  dbgftarg;                               /* actual target object */
    prpnum  dbgfprop;                          /* property being evalutated */
    int     dbgfargc;                                /* number of arguments */
    int     dbgfbif;      /* set to built-in function number if in built-in */
    uint    dbgffr;         /* offset in object of local frame symbol table */
    uint    dbgflin;                      /* OPCLINE operand of latest line */
};
typedef struct dbgfdef dbgfdef;

/* max number of frames to store in debug frame memory */
#define DBGMAXFRAME  100

/* maximum number of breakpoints set concurrently */
#define DBGBPMAX 50

/* breakpoint structure */
struct dbgbpdef
{
    objnum dbgbpself;               /* the "self" object for the breakpoint */
    objnum dbgbptarg;            /* actual target object for the breakpoint */
    uint   dbgbpofs;                  /* offset in object of the breakpoint */
    uint   dbgbpflg;                                    /* breakpoint flags */
#   define DBGBPFUSED  0x01                      /* breakpoint has been set */
#   define DBGBPFNAME  0x02              /* name of address has been stored */
#   define DBGBPFCOND  0x04          /* breakpoint has a condition attached */
#   define DBGBPFDISA  0x08                       /* breakpoint is disabled */
#   define DBGBPFCONDNAME 0x10     /* condition name string has been stored */
    uint   dbgbpnam;       /* offset of address name within dbgcxnam buffer */
    uint   dbgbpcondnam;        /* offset of condition string within buffer */
    objnum dbgbpcond;        /* object containing compiled condition for bp */
};
typedef struct dbgbpdef dbgbpdef;

/* maximum number of watch expressions set concurrently */
#define DBGWXMAX 30

/* watch expression structure */
struct dbgwxdef
{
    objnum  dbgwxobj;              /* object containing compiled expression */
    objnum  dbgwxself;                         /* 'self' for the expression */
    uint    dbgwxnam;   /* offset of expression text within dbgcxnam buffer */
    uint    dbgwxflg;               /* flags for this watch expression slot */
#   define DBGWXFUSED  0x01                         /* watch slot is in use */
#   define DBGWXFNAME  0x02                /* name of watch has been stored */
};
typedef struct dbgwxdef dbgwxdef;

/* amount of space for bp names (original address strings from user) */
#define DBGCXNAMSIZ 2048

/* debug context */
struct dbgcxdef
{
    struct tiocxdef *dbgcxtio;                          /* text i/o context */
    struct tokthdef *dbgcxtab;                              /* symbol table */
    struct mcmcxdef *dbgcxmem;              /* memory cache manager context */
    struct errcxdef *dbgcxerr;                    /* error handling context */
    struct    lindef *dbgcxlin;                    /* chain of line sources */
    int       dbgcxfcn;                          /* number of frames in use */
    int       dbgcxdep;          /* actual depth (if overflow frame buffer) */
    int       dbgcxfid;                        /* source file serial number */
    dbgfdef   dbgcxfrm[DBGMAXFRAME];                        /* stack frames */
    int       dbgcxflg;                          /* flags for debug session */
#   define    DBGCXFSS   0x01               /* single-stepping source lines */
#   define    DBGCXFSO   0x02       /* stepping over a function/method call */
#   define    DBGCXFOK   0x04                      /* debugger is linked in */
#   define    DBGCXFIND  0x08  /* in debugger - suppress stack trace on err */
#   define    DBGCXFGBP  0x10               /* global breakpoints in effect */
#   define    DBGCXFTRC  0x20                     /* call tracing activated */
#   define    DBGCXFLIN2 0x40      /* new-style line records (line numbers) */
    int       dbgcxsof;                    /* frame depth at step-over time */
    dbgbpdef  dbgcxbp[DBGBPMAX];                             /* breakpoints */
    dbgwxdef  dbgcxwx[DBGWXMAX];                       /* watch expressions */
    struct    prscxdef *dbgcxprs;                        /* parsing context */
    struct    runcxdef *dbgcxrun;                      /* execution context */
    uint      dbgcxnamf;               /* next free byte of dbgcxnam buffer */
    uint      dbgcxnams;                         /* size of dbgcxnam buffer */
    char     *dbgcxnam;                       /* space for bp address names */
    char     *dbgcxhstp;                             /* call history buffer */
    uint      dbgcxhstl;                           /* history buffer length */
    uint      dbgcxhstf;             /* offset of next free byte of history */

    /* 
     *   This member is for the use of the user interface code.  If the
     *   user interface implementation needs to store additional context,
     *   it can allocate a structure of its own (it should probably do
     *   this in dbguini()) and store a pointer to that structure here.
     *   Since the user interface entrypoints always have the debugger
     *   context passed as a parameter, the user interface code can
     *   recover its extra context information by following this pointer
     *   and casting it to its private structure type.  The TADS code
     *   won't do anything with this pointer except initialize it to null
     *   when initializing the debugger context.  
     */
    void     *dbgcxui;
};
typedef struct dbgcxdef dbgcxdef;


/* ======================================================================== */
/*
 *   Compiler interface.  These routines are called by the compiler to
 *   inform the debug record generator about important events as
 *   compilation proceeds. 
 */


/*
 *   Tell the current line source that we're compiling an executable
 *   line, and tell it the object number and offset of the code within the
 *   object. 
 */
void dbgclin(struct tokcxdef *tokctx, objnum objn, uint ofs);

/* size of information given to line source via lincmpinf method */
#define DBGLINFSIZ   4



/* ======================================================================== */
/*
 *   Run-time interface.  These routines are called by the run-time
 *   system to apprise the debugger of important events during execution.
 */


/*
 *   Determine if the debugger is present.  Returns true if so, false if
 *   not.  This should return false for any stand-alone version of the
 *   executable that isn't linked with the debugger.  If this returns
 *   true, dbgucmd() must not have a trivial implementation -- dbgucmd()
 *   must at least let the user quit out of the game.
 *   
 *   This can be switched at either link time or compile time.  If DBG_OFF
 *   is defined, we'll force this to return false; otherwise, we'll let
 *   the program define the appropriate implementation through the linker.
 */
#ifdef DBG_OFF
#define dbgpresent() (FALSE)
#else
int dbgpresent();
#endif


/* add a debug tracing record */
/* void dbgenter(dbgcxdef *ctx, runsdef *bp, objnum self, objnum target,
                 prpnum prop, int binum, int argc); */ 

/* tell debugger where the current line's local frame table is located */
/* void dbgframe(dbgcxdef *ctx, uint ofsfr, ofslin); */

/* 
 *   Single-step interrupt: the run-time has reached a new source line.
 *   ofs is the offset from the start of the object of the line record,
 *   and p is the current execution pointer.  *p can be changed upon
 *   return, in which case the run-time will continue from the new
 *   position; however, the new address must be within the same function
 *   or method as it was originally.
 */
/* void dbgssi(dbgcxdef *ctx, uint ofs, int instr,
               int err, uchar *noreg *p); */

/* pop debug trace level */
/* void dbgleave(dbgcxdef *ctx, int exittype); */
#define DBGEXRET   0                                /* return with no value */
#define DBGEXVAL   1                                 /* return with a value */
#define DBGEXPASS  2                       /* use 'pass' to exit a function */

/* dump the stack into text output */
/* void dbgdump(dbgcxdef *ctx); */

/* reset debug stack (throw away entire contents) */
/* void dbgrst(dbgcxdef *ctx); */

/* activate debugger if possible; returns TRUE if no debugger is present */
int dbgstart(dbgcxdef *ctx);

/* add a string to the history buffer */
void dbgaddhist(dbgcxdef *ctx, char *buf, int bufl);

/*
 *   Find a base pointer, given the object+offset of the frame.  If the
 *   frame is not active, this routine signals ERR_INACTFR; otherwise, the
 *   bp value for the frame is returned. 
 */
struct runsdef *dbgfrfind(dbgcxdef *ctx, objnum frobj, uint frofs);


/* ======================================================================== */
/*
 *   User Interface Support routines.  These routines are called by the
 *   user interface layer to get information from the debugger and perform
 *   debugging operations. 
 */


/* get a symbol name; returns length of name */
int dbgnam(dbgcxdef *ctx, char *outbuf, int typ, int val);

/*
 *   Get information about current line.  It is assumed that the caller
 *   knows the size of the line information .
 */
void dbglget(dbgcxdef *ctx, uchar *buf);

/*
 *   Get information about a line in an enclosing stack frame.  Level 0 is
 *   the current line, level 1 is the first enclosing frame, and so on.
 *   Returns 0 on success, non-zero if the frame level is invalid.  
 */
int dbglgetlvl(dbgcxdef *ctx, uchar *buf, int level);

/*
 *   Set a breakpoint by symbolic address: "function" or
 *   "object.property".  The string may contain whitespace characters
 *   around each symbol; it must be null-terminated.  If an error occurs,
 *   the error number is returned.  bpnum returns with the breakpoint
 *   number if err == 0.  If the condition string is given (and is not an
 *   empty string), the condition is compiled in the scope of the
 *   breakpoint and attached as the breakpoint condition.  
 */
int dbgbpset(dbgcxdef *ctx, char *addr, int *bpnum);

/* 
 *   Set a breakpoint at an object + offset location.  If 'toggle' is
 *   true, and there's already a breakpoint at the given location, we'll
 *   clear the breakpoint; in this case, *did_set will return false to
 *   indicate that an existing breakpoint was cleared rather than a new
 *   breakpoint created.  *did_set will return true if a new breakpoint
 *   was set.  
 */
int dbgbpat(dbgcxdef *ctx, objnum objn, objnum self,
            uint ofs, int *bpnum, char *bpname, int toggle,
            char *condition, int *did_set);

/* 
 *   Set a breakpoint at an object + offset location, optionally with a
 *   condition, using an existing breakpoint slot.  If the slot is already
 *   in use, we'll return an error.  
 */
int dbgbpatid(dbgcxdef *ctx, int bpnum, objnum target, objnum self,
              uint ofs, char *bpname, int toggle, char *cond,
              int *did_set);

/*
 *   Determine if there's a breakpoint at a given code location.  Fills in
 *   *bpnum with the breakpoint identifier and returns true if a
 *   breakpoint is found at the given location; returns false if there are
 *   no breakpoints matching the description.  
 */
int dbgisbp(dbgcxdef *ctx, objnum target, objnum self, uint ofs, int *bpnum);

/*
 *   Determine if the given breakpoint is enabled 
 */
int dbgisbpena(dbgcxdef *ctx, int bpnum);

/*
 *   Delete a breakpoint by breakpoint number (as returned from
 *   dbgbpset).  Returns error number, or 0 for success. 
 */
int dbgbpdel(dbgcxdef *ctx, int bpnum);

/* disable or enable a breakpoint, by breakpoint number; returns error num */
int dbgbpdis(dbgcxdef *ctx, int bpnum, int disable);

/*
 *   Set a new condition for the given breakpoint.  Replaces any existing
 *   condition.  If an error occurs, we'll leave the old condition as it
 *   was and return a non-zero error code; on success, we'll update the
 *   condition and return zero. 
 */
int dbgbpsetcond(dbgcxdef *ctx, int bpnum, char *cond);

/* list breakpoints, using user callback to do display */
void dbgbplist(dbgcxdef *ctx,
               void (*dispfn)(void *ctx, const char *str, int len),
               void *dispctx);

/* enumerate breakpoints */
void dbgbpenum(dbgcxdef *ctx,
               void (*cbfunc)(void *cbctx, int bpnum, const char *desc,
                              const char *cond, int disabled), void *cbctx);

/* call callback with lindef data for each breakpoint currently set */
void dbgbpeach(dbgcxdef *ctx,
               void (*fn)(void *, int, uchar *, uint),
               void *fnctx);

/* 
 *   Get information on a specific breakpoint.  Returns zero on success,
 *   non-zero on failure. 
 */
int dbgbpgetinfo(dbgcxdef *ctx, int bpnum, char *descbuf, size_t descbuflen,
                 char *condbuf, size_t condbuflen);

/* 
 *   Evaluate an expression (a text string to be parsed) at a particular
 *   stack context level; returns error number.  Invokes the callback
 *   function repeatedly to display the value string, and ends the display
 *   with a newline.  If showtype is true, we'll include a type name
 *   prefix, otherwise we'll simply display the value.  
 */
int dbgeval(dbgcxdef *ctx, char *expr,
            void (*dispfn)(void *dispctx, const char *str, int strl),
            void *dispctx, int level, int showtype);

/*
 *   Evaluate an expression, extended version.  For aggregate values
 *   (objects, lists), we'll invoke a callback function for each value
 *   contained by the aggregate value, passing the callback the name and
 *   relationship of the subitem.  The relationship is simply the operator
 *   that should be used to join the parent expression and the subitem
 *   name to form the full subitem expression; for objects, it's ".", and
 *   for lists it's null (because for lists the subitem names will include
 *   brackets).  'speculative' is passed to dbgcompile; see the comments
 *   there for information on the purpose of this flag.  
 */
int dbgevalext(dbgcxdef *ctx, char *expr,
               void (*dispfn)(void *dispctx, const char *str, int strl),
               void *dispctx, int level, int showtype, dattyp *dat,
               void (*aggcb)(void *aggctx, const char *subname,
                             int subnamelen, const char *relationship),
               void *aggctx, int speculative);

/* 
 *   enumerate local variables at a given stack context level by calling
 *   the given function once for each local variable 
 */
void dbgenumlcl(dbgcxdef *ctx, int level,
                void (*func)(void *ctx, const char *lclnam, size_t lclnamlen),
                void *cbctx);

/* 
 *   Compile an expression in a given frame context.  Returns an error
 *   number.  Allocates a new object to contain the compiled code, and
 *   returns the object number in *objn; the caller is responsible for
 *   freeing the object when done with it.
 *   
 *   If 'speculative' is set to true, we'll prohibit the expression from
 *   making any assignments or calling any methods or functions.  This
 *   mode can be used to try compiling an expression that the user could
 *   conceivably be interested in but has not expressly evaluated; for
 *   example, this can be used to implement "tooltip evaluation," where
 *   the debugger automatically shows a little pop-up window with the
 *   expression under the mouse cursor if the mouse cursor is left
 *   hovering over some text for a few moments.  In such cases, since the
 *   user hasn't explicitly requested evaluation, it would be bad to make
 *   any changes to game state, hence the prohibition of assignments or
 *   calls.  
 */
int dbgcompile(dbgcxdef *ctx, char *expr, dbgfdef *fr, objnum *objn,
               int speculative);

/* display a stack traceback through a user callback */
void dbgstktr(dbgcxdef *ctx,
              void (*dispfn)(void *dispctx, const char *str, int strl),
              void *dispctx, int level, int toponly, int include_markers);

/* format a display of where execution is stopped into a buffer */
void dbgwhere(dbgcxdef *ctx, char *buf);

/* set a watch expression; returns error or 0 for success */
int dbgwxset(dbgcxdef *ctx, char *expr, int *wxnum, int level);

/* delete a watch expression */
int dbgwxdel(dbgcxdef *ctx, int wxnum);

/* update all watch expressions */
void dbgwxupd(dbgcxdef *ctx,
              void (*dispfn)(void *dispctx, const char *txt, int len),
              void *dispctx);

/* switch to a new active lindef */
void dbgswitch(struct lindef **linp, struct lindef *newlin);



/* ======================================================================== */
/*
 *   User Interface Routines.  The routines are called by the debugger
 *   to perform user interaction.
 */

/* 
 *   Debugger user interface initialization, phase one.  TADS calls this
 *   routine during startup, before reading the .GAM file, to let the user
 *   interface perform any initialization it requires before the .GAM file
 *   is loaded.  
 */
void dbguini(dbgcxdef *ctx, const char *game_filename);

/*
 *   Debugger user interface initialization, phase two.  TADS calls this
 *   routine during startup, after read the .GAM file.  The debugger user
 *   interface code can perform any required initialization that depends
 *   on the .GAM file having been read.  
 */
void dbguini2(dbgcxdef *ctx);

/*
 *   Determine if the debugger can resume from a run-time error.  This
 *   reflects the capabilities of the user interface of the debugger.  In
 *   particular, if the UI provides a way to change the instruction
 *   pointer, then the debugger can resume from an error, since the user
 *   can always move past the run-time error and continue execution.  If
 *   the UI doesn't let the user change the instruction pointer, resuming
 *   from an error won't work, since the program will keep hitting the
 *   same error and re-entering the debugger.  If this returns false, the
 *   run-time will trap to the debugger on an error, but will simply abort
 *   the current command when the debugger returns.  If this returns true,
 *   the run-time will trap to the debugger on an error with the
 *   instruction pointer set back to the start of the line containing the
 *   error, and will thus re-try the same line of code when the debugger
 *   returns, unless the debugger explicitly moves the instruction pointer
 *   before returning.  
 */
int dbgu_err_resume(dbgcxdef *ctx);

/*
 *   Find a source file.  origname is the name of the source file as it
 *   appears in the game's debugging information; this routine should
 *   figure out where the file actually is, and put the fully-qualified
 *   path to the file in fullname.  The debugger calls this after it
 *   exhausts all of its other methods of finding a source file (such as
 *   searching the include path).
 *   
 *   Return true if the source file should be considered valid, false if
 *   not.  Most implementations will simply return true if the file was
 *   found, false if not; however, this approach will cause the debugger
 *   to terminate with an error at start-up if the user hasn't set up the
 *   debugger's include path correctly before running the debugger.  Some
 *   implementations, in particular GUI implementations, may wish to wait
 *   to find a file until the file is actually needed, rather than pester
 *   the user with file search dialogs repeatedly at start-up.
 *   
 *   must_find_file specifies how to respond if we can't find the file.
 *   If must_find_file is true, we should always return false if we can't
 *   find the file.  If must_find_file is false, however, we can
 *   optionally return true even if we can't find the file.  Doing so
 *   indicates that the debugger UI will defer locating the file until it
 *   is actually needed.
 *   
 *   If this routine returns true without actually finding the file, it
 *   should set fullname[0] to '\0' to indicate that fullname doesn't
 *   contain a valid filename.  
 */
int dbgu_find_src(const char *origname, int origlen,
                  char *fullname, size_t full_len, int must_find_file);


/* 
 *   Debugger user interface main command loop.  If err is non-zero, the
 *   debugger was entered because a run-time error occurred; otherwise, if
 *   bphit is non-zero, it's the number of the breakpoint that was
 *   encountered; otherwise, the debugger was entered through a
 *   single-step of some kind.  exec_ofs is the byte offset within the
 *   target object of the next instruction to be executed.  This can be
 *   changed upon return, in which case execution will continue from the
 *   new offset, but the offset must be within the same method of the same
 *   object (or within the same function) as it was upon entry. 
 */
void dbgucmd(dbgcxdef *ctx, int bphit, int err, unsigned int *exec_ofs);

/*
 *   Debugger UI - quitting game.  The runtime calls this routine just
 *   before the play loop is about to terminate after the game code has
 *   called the "quit" built-in function.  If the debugger wants, it can
 *   take control here (just as with dbgucmd()) for as long as it wants.
 *   If the debugger wants to restart the game, it should call bifrst().
 *   If this routine returns without signalling a RUN_RESTART error, TADS
 *   will terminate.  If a RUN_RESTART error is signalled, TADS will
 *   resume the play loop.  
 */
void dbguquitting(dbgcxdef *ctx);

/* 
 *   debugger user interface termination - this routine is called when the
 *   debugger is about to terminate, so that the user interface can close
 *   itself down (close windows, release memory, etc) 
 */
void dbguterm(dbgcxdef *ctx);

/*
 *   Debugger user interface: display an error.  This is called mainly so
 *   that the debugger can display an error using special output
 *   formatting if the error occurs while debugging. 
 */
void dbguerr(dbgcxdef *ctx, int errnum, char *msg);

/* turn hidden output tracing on/off */
void trchid(void);
void trcsho(void);


/* ======================================================================== */
/*
 *   optional debugger macros - these compile to nothing when compiling a
 *   version for use without the debugger 
 */

#ifdef DBG_OFF
# define dbgenter(ctx, bp, self, target, prop, binum, argc)
# define dbgleave(ctx, exittype)
# define dbgdump(ctx)
# define dbgrst(ctx) ((void)0)
# define dbgframe(ctx, frofs, linofs)
# define dbgssi(ctx, ofs, instr, err, p)
#else /* DBG_OFF */
# define dbgenter(ctx, bp, self, target, prop, binum, argc) \
   dbgent(ctx, bp, self, target, prop, binum, argc)
# define dbgleave(ctx, exittype) dbglv(ctx, exittype)
# define dbgdump(ctx) dbgds(ctx)
# define dbgrst(ctx) ((ctx)->dbgcxfcn = (ctx)->dbgcxdep = 0)
# define dbgframe(ctx, frofs, linofs) \
   (((ctx)->dbgcxfrm[(ctx)->dbgcxfcn - 1].dbgffr = (frofs)), \
    ((ctx)->dbgcxfrm[(ctx)->dbgcxfcn - 1].dbgflin = (linofs)))
# define dbgssi(ctx, ofs, instr, err, p) dbgss(ctx, ofs, instr, err, p)
#endif /* DBG_OFF */


/* ======================================================================== */
/* private internal routines */

void dbgent(dbgcxdef *ctx, struct runsdef *bp, objnum self, objnum target,
            prpnum prop, int binum, int argc);

void dbglv(dbgcxdef *ctx, int exittype);

void dbgds(dbgcxdef *ctx);

void dbgss(dbgcxdef *ctx, uint ofs, int instr, int err, uchar *noreg *p);

void dbgpval(struct dbgcxdef *ctx, struct runsdef *val,
             void (*dispfn)(void *, const char *, int),
             void *dispctx, int showtype);

int dbgtabsea(struct toktdef *tab, char *name, int namel, int hash,
              struct toksdef *ret);


#ifdef __cplusplus
}
#endif

#endif /* DBG_INCLUDED */