Introduction

The Xinu Post-Mortem Debugger (PMD) is a utility for examining a Xinu core image. PMD is not a true debugger--it cannot set breakpoints, single step through code, or do anything that the more sophisticated debuggers do. Instead, PMD analyzes the state of Xinu after your Xinu program has completed, crashed, or has been interrupted by a break signal. In fact, a better name for PMD would be ``Post-Mortem Analyzer''.

Specifically, PMD allows you to:

• examine the process, tty, and semaphore tables
• compare the text segment of the core image with the original
• print values of global variables
• check the state of Xinu at the time it halted

Entering and Exiting PMD

PMD should only be used after you have executed your Xinu program at least once. PMD analyzes the Sun's memory based on symbol table information within the executable residing in your current directory. If you have not executed your Xinu program at least once, then PMD's analysis will be meaningless. You must make certain that the core image in memory corresponds to what PMD expects to be in memory (see the set command.) To exit PMD, type q at the monitor prompt and hit RETURN. You will see the Sun monitor prompt. All keyboard input is now sent to the Sun monitor. Sending a break signal (\b) will also leave PMD.

Commands

• check [arg]..... Check the text or current Xinu status
• dump [arg]...... Dump a Xinu table
• help............ Print a command summary
• print [name].... Dump the memory contents of [name]
• quit............ Quit PMD
• set [name]...... Set the executable file to [name]
• verbose......... Toggle verbosity level

The Check Command

The check text command downloads the text segment of the Xinu core image from the Sun and compares it with the original text that was uploaded to the Sun. Any differences between the two are printed to the screen. Differences between the text segments indicate a severe error. Possibilities include:

• an incorrect executable file is specified (this will be explained later)
• an error occurred in the download procedure (not common)
• an accidental text overwrite (likely by a ``stray'' pointer dereference)

Because the text segment is rather large, it takes a fair bit of time to download. The check text command, along with many of the other commands in PMD, will inform the user when it is downloading memory from the Sun machine. A period (.) will be printed for every kilobyte of Sun memory transferred. In any operation that involves downloading memory, you may type q in the middle of the download procedure to abort it.

The Dump Command

The process table dump includes a stack traceback of all processes in the process table. The stack traceback will print the symbolic name of the function that was called along with the parameters (in parentheses) that were pushed on the stack upon invocation of the function. PMD prints the pushed stack data as a series of integers up to the next return address. Since PMD has no type information of the stack data, the parameters printed in parentheses will likely not correspond to what you intended to pass as a parameter. In other words, the information printed in parentheses is to be taken lightly. PMD also allows the dumping of arbitrary tables. To do so, you will need a file named config in the current directory. The config file must specify the name of the table, the number of entries in the table, and a list of fields that you wish to print.

It is probably best to give an example to show how the config file must be set up:

_semaph 50
{
	2 state %C;
	4 count %d;
	4 head  %d;
	4 tail  %d;
}

_proctab 30
{
	2  pstate %C;
	4  pprio %d;
	60 dummy %z;
	4  SSP %x;
	4  SR %x;
	4  PC %x;
	14 dummy %z;
	4  pbase %x;
	4  pstklen %x;
	4  plimit %x;
	16 pname %s;
	96 dummy %z;
}

Any number of tables may be present within the config file. Note that the curly braces and semicolons are necessary, since PMD uses these symbols to parse your config file. The first item must be the name of the table which must have the underscore prefix. This must be the same name that is used in the Xinu source code. The next item is the number of entries in the table. In the previous example, these correspond to the NSEM and NPROC macros in the Xinu source code. Between the parentheses is a list of the fields which are to be printed. Each field contains a number, a name and a format specification. The number indicates the number of bytes that this field occupies. The name is a character string which will be printed before the value of the field is printed. Finally, the format specification is used to tell PMD how to print the field. This string must begin with a percent sign. This string is simply passed to a printf() function, so the format specification works exactly the same as it does for printf() (so you can use %08.3s for floating point, for example.)

There are some important things to note:

• A char will not always be one byte. The C compiler often performs word alignment, so you will often find the size of a char within a structure to be two bytes.
• The %z format specification is used to skip fields. The specified number must be the number of bytes you wish to skip. Also note that the name must still be specified or a syntax error will result.
• The %C format specification is a special case used for char. This has the effect of printing the appropriate value of the character as an integer. Do not use %d or you will get an incorrect answer. Remember that %c will print the actual ASCII character.
• The sum of all the field sizes must add up to the size of the table entry. PMD will check for this and refuse to output data unless you have done this correctly.

You may have to play around with the config file to get the data output correctly. A ``standard'' config file will be made available for you to use. Ordinarily, PMD reads the config file once, and uses that to interpret the downloaded core. You can force PMD to re-read your config file by use of the reload command. Simply type r and PMD will re-read your config file.

To output the table, you simply have to use the dump command. In the previous example, you would dump the semaphore table by typing dump _semaph. PMD distinguishes between a normal table dump and a custom table dump by looking at the underscore character, so you must include it in the dump command.

The Help Command

The Print Command

Since you may dump the value of any global symbol, there is no reason why you cannot dump the memory contents of a function. Typing print _main will actually print a hex dump of the function main(). Future versions of PMD may implement disassembly the hex dump.

The Set Command

If you decide to execute a different program such as prog3, be sure to use the set command to tell PMD of the new file that is in memory. You can find the name of the current file that PMD expects to be in memory by issuing the help command.

The Verbose Command

Limitations and Bugs

PMD's implementation is extremely hardware specific. PMD issues monitor commands to obtain the core image of Sun memory. The routines are quite sensitive to how the Sun monitor responds to these commands.

PMD is able to download various parts of the Xinu kernel such as the process table. Because PMD downloads a raw Xinu core image, it extracts information from the image in a compiler specific way. Changing the cross compiler will mean editing the source code to adjust to the new compiler.

PMD will not work entirely for some CPSC 415 assignments involving editing of the Xinu kernel. When PMD downloads tables from the Sun, it expects the data within to be exactly as that found in the Sun version of Xinu 7.0. If any changes are made to the semaphore, process, or tty table, then PMD cannot be used to dump that particular table. Doing so will result in unpredictable behaviour.