$Id: LibDebug.txt,v 1.6 2001/04/26 23:11:44 cosine Exp $
 
 libDebug handles all of the operating system specific calls
during the course of debugging an executable program. This file
will attempt to adequately document the routines contained in
this library, should anyone decide to use it for their own programs.

Terminology

  external program: This refers to the program calling routines in
                    libDebug

Routines:

=======================================================================
void InitializeDebugProcess(path, redirect)
  char *path   - path to program
  int redirect - redirect IO

  This routine must be called every time you get a new file ready
for debugging. The library needs to know the path to the program
for when it actually loads the program into memory. If redirect
is set to 1, all the IO from the program (on stdin, stdout, and stderr)
will be captured and made available to the external program.

Return: none
=======================================================================
int SingleStepInto(num, data)
  int num   - number of instructions to singlestep (into)
  int *data - used to store extra information depending upon the
              return result
int SingleStepOver(num, data)
  int num   - number of instructions to singlestep (over)
  int *data - used to store extra information depending upon the
              return result
int ContinueDebugProcess(data)
  int *data - used to store extra information depending upon the
              return result

  SingleStepInto will singlestep 'num' instructions, stepping into
any subroutines. SingleStepOver will singlestep 'num' instructions,
stepping over any subroutines. ContinueDebugProcess will continue
executing the program from where it left off.

All of these functions return the following values:
  0 if unsuccessful (normally a ptrace error)
  1 if successful (everything went normally)
  2 if a signal was caught (data is modified to contain signal number)
  3 if a breakpoint is encountered (data will contain the breakpoint
    number)
  4 if the program terminates normally (data will contain the exit
    status)
  5 if program outputs data to stdout or stderr and IO was set
    to redirect. The actual data can be read through the
    GetDebugOutput() routine.
=======================================================================
char **GetAllRegisters(count, regindex)
  int *count   - modified to contain the number of registers
  int regindex - optional index corresponding to a specific register
                 to display

  This routine will get the list of registers and their values and
return a pointer to an array where the information is stored.

Return: pointer to an array of strings containing register(s) and
        their values. Memory is allocated for this array, so it must
        be freed by the calling routine.
=======================================================================
int FindRegister(name)
  char *name - name of a specific register to look up

  Attempts to find a register matching the given string.

Return: an internal array index matching the given register - this
        index will have no significance to the external program,
        but it must be provided to SetRegister(), should the external
        program wish to change the register's value.
        -1 is returned if no register matching the given name is found.
=======================================================================
int SetRegister(regindex, value)
  int regindex - index of register (can be obtained via FindRegister())
  long value   - new value

  Set a register to a given value.

Return: 1 if successful, 0 if not
=======================================================================
long GetRegister(regindex)
  int regindex - index of register (can be obtained via FindRegister())

  Get register contents

Return: contents of register specified by regindex
=======================================================================
long DumpMemory(buf, start, bytes)
  char **buf          - buffer to store memory bytes in
  unsigned long start - address to start dump
  long bytes          - number of bytes to dump

  Dumps memory contents of debugged process.

Return: number of bytes dumped - if this value is less than 'bytes',
        an error occurred and errno should be set appropriately.

Side effects: upon success, memory is allocated for 'buf', so it must
              be freed by the calling function.
=======================================================================
int SetMemory(address, value)
  unsigned long address
  unsigned long value

  Set memory location 'address' to 'value' (sets only the lowest
byte of 'value').

Return: 0 if unsuccessful (normally a ptrace() error)
        number of bytes written if successful
=======================================================================
unsigned long GetInstructionAddress()

Return: (virtual) address of next instruction to be executed.
=======================================================================
int FindDebugProcess()

Return: if the debugged process is currently running, returns 1.
        Otherwise, 0.
=======================================================================
void EndDebugProcess()

  Use this function to terminate (kill) the program - cleans up
some variables etc.

Return: none
=======================================================================
char *GetDebugOutput()

Return: pointer to buffer containing output from the debugged program's
        stdout or stderr writes.
=======================================================================
Breakpoint related routines
=======================================================================
int SetBreakpoint(address, flags)
  unsigned long address - address of the instruction to break
  unsigned int flags    - various flags for the breakpoint

  Sets a new breakpoint at the given address with the given flags.

Flag values (defined in break.h):
  BK_TEMPORARY - indicates a temporary breakpoint which is cleared
                 after it is triggered.

Return: breakpoint number, or -1 if error occurs
=======================================================================
void DeleteBreakpoint(ptr)
  struct Breakpoint *ptr - pointer to breakpoint structure

  Deletes the given breakpoint.

Return: none
=======================================================================
void ClearBreakpoints()

  Deletes all breakpoints.

Return: none
=======================================================================
int EnableBreakpoints()

  Activates all breakpoints marked as enabled - this is usually only
called internally to activate breakpoints before singlestepping or
continuing the process. External programs will normally not need this
function.

Return: 1 if successful, 0 if not
=======================================================================
int DisableBreakpoints()

  Disables all breakpoints marked as enabled - again, this is normally
an internal function not needed by external programs.

Return: 1 if successful, 0 if not
=======================================================================
struct Breakpoint *FindBreakpoint(address)
  unsigned long address - address of breakpoint

  Attempt to locate the breakpoint with the given address.

Return: a pointer to the breakpoint if found, 0 if not
=======================================================================
struct Breakpoint *FindBreakpointByNumber(number)
  long number - number of breakpoint

  Attempt to locate the breakpoint with the given number.

Return: a pointer to the breakpoint if found, 0 if not
=======================================================================
void DeactivateBreakpoint(ptr)
  struct Breakpoint *ptr - pointer to breakpoint. This value can also
                           be NULL, indicating to deactivate all
                           breakpoints.

  Mark the breakpoint as inactive - it is not deleted, but it will
not stop the program.

Return: none
=======================================================================
void ActivateBreakpoint(ptr)
  struct Breakpoint *ptr - pointer to breakpoint. This value can also
                           be NULL, indicating to activate all
                           breakpoints.

  Mark the breakpoint as active - this reverses the effects of
DeactivateBreakpoint().

Return: none
=======================================================================
void SetIgnoreCount(ptr, count)
  struct Breakpoint *ptr - pointer to breakpoint
  long count             - new ignore count

  This sets the ignore count for a breakpoint. With an ignore count,
a breakpoint will not be triggered until it has been hit <count>
times.

Return: none
=======================================================================
Argument related routines
=======================================================================
char *GetProcessPath()

Return: path to the program currently being debugged.
=======================================================================
void SetProcessArguments(args)
  char *args - runtime arguments to program

  Sets the runtime arguments to the program being debugged.

Return: none
=======================================================================
char *GetProcessArguments()

Return: a pointer to the runtime arguments to the program.
=======================================================================
