NAME

kdbx − Sprite debugger

SYNOPSIS

kdbx [ −ip ] [ −I dir ] [ −c file ] [ −h hostname ] [objfile]

DESCRIPTION

kdbx is a debugger which can be used to debug the Sprite kernel.  kdbx is nearly identical to dbx.  The only difference is the relationship between the debugger (kdbx) and the debuggee (the kernel).  This manual page describes how kdbx must be used differently because of the different debugging relationship.  Since kdbx accepts all options and commands of dbx, these are not described in this manual page.  A complete reference of all of the options and the commands accepted by kdbx is contained in dbx(1). 

Starting up Kdbx

The Sprite debugging facilities are broken into two pieces: the piece which resides in the Sprite kernel and kdbx which runs on a Unix machine.  The Sprite kernel and kdbx communicate across a serial line or the ethernet.  In order to use kdbx on the kernel, the kernel must be forced into the debugging routine so that it can communicate to kdbx.  Once this is accomplished, kdbx can be used on the kernel just like dbx can be used on a normal stopped process.  Thus, the normal two step sequence needed to startup kdbx on the kernel is:

1)Force the kernel into the debugging routine.  The method of accomplishing this will be explained below. 

2)Invoke kdbx like dbx.  For example, the normal command would be “kdbx -I ../Installed/mod.o -h hostname sprite”. 

It is also possible to invoke “kdbx -p ...” to indicate that kdbx should read the symbol table but prompt the user before communicating with the Sprite kernel.  In this case, kdbx may be invoked before Sprite enters the debugger, thus overlapping some of the overhead of booting and debugging. 

By default kdbx uses the serial line for debugging.  The kernel on the other hand defaults to the network.  In order to have kdbx use the network the -h flag must be used in order to specify the name of the host that is to be debugged.  There are two methods of making the sprite kernel use the serial line instead of the network.  First, the L1-B key described below can be used.  Second, the kernel can be recompiled with the dbg_Rs232Debug flag set to TRUE (it is set to FALSE by the dbg module by default).  This can be done in the mainHook.c file that is in each kernel’s directory. 

There are several different ways to force the kernel into the debugging routine.  The first method of entering the debugging routine is by an unhandled exception which the operating system encountered.  If this happens then no further manipulation of the kernel is required and kdbx can be invoked directly.  The second method is by putting a call to the debugger in the operating system code.  This is done by including dbg.h and entering the macro DBG_CALL at the point where you wish the debugger to be called.  An example piece of C code which uses this macro is

Sys_Printf("Kernel foobared");
DBG_CALL;

If this method is used, then kdbx can be invoked directly. 

If the kernel is not already in the debugging routine, then it must be interrupted and forced into the debugging routine.  The easiest way to do this is to type L1-D at the console of the kernel being debugged.  This will immediately force the kernel into the debugger and kdbx can be invoked on the kernel.  In this case the debugger will use the network regardless of the value of the dbg_Rs232Debug flag.  In order to use the serial line use L1-B instead. 

Another simple way of forcing the kernel into the debugger is to issue the command “l1d hostname” which will send a debug message to the kernel. 

A more complicated method of forcing the kernel into the debugger is:

1)Type an L1-A at the console of the kernel being debugged.  After typing this the program counter (PC) where the kernel was interrupted will be printed out. 

2)Type the command L a04008 addr where addr is the PC that was printed out in step 1. 

3)Type the command C a04006. 

After this last step the kernel debugger will have been entered and kdbx can now be invoked on the kernel. 

Using Kdbx

Once kdbx has been invoked on the kernel it can be used almost exactly like dbx.  All of the commands that work in dbx will also work in kdbx (i.e.  setting of breakpoints, single stepping, tracing, printing of variables, etc.).  The only difference when using kdbx is if after typing a “cont” command you wish to interrupt the kernel to get back into kdbx.  When using normal dbx a control-C can be typed at the terminal to interrupt the debugged process.  This will not work with kdbx.  In order to interrupt the kernel you must use the same method that was given above for entering the kernel debugging routine from the console.  Once this is done then kdbx will get the interrupt. 

Quitting Kdbx

Kdbx can be exited just like dbx; that is, by using the “quit” command.  When kdbx is exited the kernel will resume where kdbx tells it to resume. 

Additions to Kdbx

The part of the debugger which resides in the Sprite kernel saves the state of the kernel when it is entered.  Kdbx is aware of part of this state (such as the program counter and the general purpose registers) but is unaware of most of it.  In order to get at this information the variables which contain this information can be printed out in kdbx by using the normal print command.  These variables include:

dbgSfcReg
The source function code register.

dbgDfcReg
The destination function code register.

dbgUserContext
The user context register.

dbgKernelContext
The kernel context register.

dbgTrapStack
The stack that was created when the debugger was entered. This includes the bus error register, the user stack pointer, the 16 general purpose registers in the order d0-d7, a0-a7, and the exception stack. The exception stack includes the pc and the status register. See the header file exc.h for the exact format of the trap stack and the exception stack.

In the normal case kdbx will only backtrace the stack of the process that was executing when the debugger was entered.  If you wish to backtrace the stack of some other waiting process then go through the following steps:

1)Enter the command “set $index = process-table-index” where process-table-index is the index of the process control block of the process whose stack you want to trace. 

2)Now issue the normal “where” command. 

3)Go back to the original process by issuing the command “set $index = 0”. 

Note that the only command that should be executed after switching processes is the where command.  Continuing the kernel after switching stacks would be a disaster. 

Modifications to Kdbx

There have been several modifications to kdbx:

1)Parameter types are not checked when calling functions inside of kdbx. 

2)Objects of type “char ∗” are not dereferenced automatically.  There are two ways to make them be dereferenced while using the “print” command.  One is to issue the command “ps” (an alias for print string) instead of “print”.  The other is to automatically set the variable $dref (i.e. use the command “set $dref”).  This will make all subsequent “print” commands dereference strings. 

BUGS

A good chunk of this man page is out of date.  We currently only use kdbx on Decstation 3100s.  Other machines use kgdb, and we plan to switch 3100s to kgdb, too.  Look at the script /sprite/src/kernel/sprite/Kdbx for the correct way to invoke kdbx. 

SEE ALSO

dbx, kgdb

KEYWORDS

debugger, dbx, sprite debugger, kernel debugger

Sprite version 1.0  —  October 18, 1990