.TH DMDPI 1 "630 MTG" .SH NAME dmdpi \- 630 MTG process inspector and debugger .SH SYNOPSIS .B dmdpi [ -c ] .SH DESCRIPTION .I Dmdpi is a C language debugger that is bound dynamically to multiple subject processes executing in a 630 MTG window in the layers environment. In order to use dmdpi to its full capabilities, it is necessary to compile the source program with the .I -g option of .IR dmdcc . However, if the target program is not compiled with .I -g, or no symbol tables at all are available, dmdpi works as well as possible with the information provided to it. .PP If the -c option is selected, \f2dmdpi\f1 will be cached in the 630 MTG cache system. This will enable \f2dmdpi\f1 to be executed again without the need for another download. .PP Dmdpi uses a multi-window user interface. There are three types of windows: debugger control windows, which access the global state of the debugger; process control windows (exactly one per process), which start and stop processes and connect to process-specific functions; and process inspection windows, which include viewers for source text and memory, formatted various ways. Initially, there are three debugger control windows available: \fBdmdpi\fR, \fBhelp\fR and \fBpwd/cd\fR. .P One might need to debug some initialization code that would ordinarily be executed before dmdpi has a chance to gain control of the process. The \fI-z\fR of \fIdmdld\fR is useful for this purpose. This allows you to take control of a process before the first statement is executed. See the \fIdmdld(1)\fR manual page for details on using this option. .SS User Interface Button 1 points. Pointing at a window makes it current, noted with a highlighted border; pointing at a line of text makes it current and inverts its video. A scroll bar at the left of each window shows how much of the text of a window is visible; pointing into the scroll region and moving the mouse controls what text is displayed. .PP Button 2 has a menu of operations that apply to the current line. Operations above the .B ~~~~~ separator are specific to each line; operations below the separator are generic line operations: .TP 1i .B cut Remove the line. .TP .B sever Remove the line and all lines above it. .TP .B fold Wrap the line, if it extends past the right margin. .TP .B truncate Truncate the line at the right margin. .LP Button 3 has a menu of window-level operations and is in two parts. Operations above the separator are specific to each window. Operations below the separator are the following generic window operations: .TP 1i .B reshape Change the size of a window. .TP .B move Move a window to a different place. .TP .B close Delete a window. .TP .B fold Like button 2 fold above except it applies to all lines in the window. .TP .B truncate Like button 2 truncate above except it applies to all lines in the window. .TP .B top The sub-menu off the \fBtop\fR is a list of windows; selecting one makes it top and current. .LP Button 3 also is also used to sweep out new windows. .PP Keyboard characters accumulate at the bottom of the window. If the current line accepts input, it flashes with each keystroke; otherwise, if the current window accepts input, its border flashes. Carriage return is ignored until a line or window accepts the text, whereupon the input line is sent to the line or window. .PP The following keyboard commands are also available: .TP .B "\'>file\'" This saves the contents of the current line, or current window if there is no current line, into the named file. To achieve the status of no current line in the window, scroll off the top or bottom of the window. .TP .B "\'state variable is displayed and updated. .PP The menu operations on the process are: .TP 1i .PD 0 .B run let the process run .TP .B stop stop the process .TP .B src text open source text window(s) .TP .B Globals open window for evaluating expressions in global scope .TP .B RawMemory open window for editing uninterpreted memory .TP .B Assembler open window for disassembler .TP .B User Types open window for setting user types .TP .B Journal open debugging session journal window .TP .B Bpt List open breakpoint list window .PD .LP Each line of the call stack traceback describes one function. Each function in the traceback can open a stack frame expression evaluator window or display its current source line. .SS Process Inspection Windows .TP .B Source Text Windows The source text window contains a listing of a source file. If there is more than one source file for the process, selecting the .B src text item in the process control window will give you a source files window in which there is a listing of all the source files associated with that process. Library function source files are included in this list, even though one might not actually have the source for these functions. By highlighting a source line and selecting .B open source file in the button 2 menu, you can open a source listing for that file. Each source file is in a separate window, which can be opened when needed. The source files are searched for in the working directory. Entering a pathname from the keyboard (when the Source files window is current) enters a pathname prefix which points to a directory where the source can be found, without changing the working directory. .RS .P When opening a source file, dmdpi checks to see whether the source file is in time sync with the object module. If not, dmdpi gives a message of this fact. One may override this condition with the .B reopen item in the button 3 menu of the source text window. Source lines are displayed on a "per request basis." In other words, only the lines that are currently visible are sent from the host. More lines are sent to be displayed on the terminal as needed. .P Specific strings may be searched for in the source text by using \fI/string\fR, or the \fI?string\fR entered at the keyboard, for searching forward and backward in the source text respectively. The search will begin at the next (previous for backwards search) C language statement rather than at the next source line. Note that repeated reverse searches for the same pattern must be specified as \fI??\fR rather than \fI?\fR due to a conflict with the help operator (?). Line numbers can also be searched for by entering a line number at the keyboard when a line is not current within the window. If a line is current, the number is evaluated as a constant expression (see expressions below). To achieve the status of no current line, scroll the current line off the top or bottom of the window. .P .B Breakpoints are set on source lines. A breakpoint is set by highlighting the line on which you wish to break execution and selecting .B set bpt from the button 2 menu. A breakpoint is denoted by a '>>>' next to the source line. When the process reaches this line the process halts and will not execute the line on which the breakpoint is set. Clearing the breakpoint is done by highlighting the line on which a breakpoint is set and selecting .B clear bpt from the button 2 menu. Clearing the breakpoint can also be done from the breakpoint list window (see below). A .B conditional breakpoint is a breakpoint that is set with a certain condition. When this condition evaluates to TRUE, the process is halted. Any valid dmdpi expression may be used as a condition (see keyboard expressions). To set a conditional breakpoint, select .B cond bpt from the button 2 menu. You are prompted to enter an expression from the keyboard as a condition. An example of a condition would be (x==1). When the variable x becomes equal to 1, then execution breaks. The .B trace on item in the button 2 menu is actually a conditional breakpoint with the condition of 0, meaning that the condition never evaluates to TRUE. This has the effect of tracing a statement but never breaking execution. The conditional breakpoint is removed in the same way a regular breakpoint is removed. .P Once the process has been halted, select \f3run\f1 to start the process running again. You can also .B step (execute) a number of source lines and then stop again after these statements have been executed. When statements are stepped, the debugger will not enter functions unless the .B step into fcn item is actually specified. The current statement can always be seen by selecting the .B current stmt item in the button 3 menu. This highlights the statement currently in the PC. .P Another option that is available in the source text window is the ability to look at the assembly code for a specified line. Highlighting a line and selecting .B assembler in the button 2 menu displays the first assembler instruction of the statement. .RE .TP .B Globals and Stack Frame Windows A stack frame window is opened from a line in the call stack traceback in the process control window or from a line of source text. A globals window is opened from the button 3 menu in the process control window. These windows evaluate expressions with respect to global scope, and scope in a function, respectively. .RS .P .B "Expressions" .P Expressions may be entered from the keyboard or with the mouse. The syntax for expressions in dmdpi is the same as C language expressions, except for differences noted below. The expressions are most commonly used for inspecting values of variables in the program that is being debugged. An example of an expression is .I r.origin.x. This may be typed in order to inspect the x coordinate value of a rectangle origin point if the process has a rectangle .I r. .P A summary of dmdpi's expression syntax is presented here only to aid comprehension, rather than an exact statement of the language. .RE .sp .RS \fI expression : constant primary \(**expression &expression -expression !expression ~expression sizeof expression typeof expression fabs (expression) (type-name) expression /\(** from menu only \(**/ {expression} identifier expression binop expression expression = expression expression , expression primary: $ identifier ( expression ) primary ( [expression-list] ) primary[ expression ] lvalue.identifier primary -> identifier lvalue: identifier primary[expression] lvalue.identifier primary -> identifier \(**expression (lvalue) binop: \(** / % + - >> << < > <= >= == != & ^ | && || \fR .P The major differences in the expressions which dmdpi understands and the C expressions are: .IP "" The unary operators \fIfabs\fR and \fItypeof\fR are supported. .I fabs evaluates the absolute value of a floating point number. .I typeof evaluates the type of an expression. Examples are: .br fabs(-2.0)=2 .br typeof(r.origin)= struct Point .IP "" The concept of a "current expression" has been introduced with the .B $ operator. .B $ is equal to the current highlighted expression. For example, if the line containing \fIr.origin\fR is highlighted, one may type .B $.x to see the value of the x coordinate. Another example of the .B $ expression is .B $=. This can be used, for instance if .B $ is equal to a variable x and you wish to change the value of x to . .IP "" Expressions are evaluated within the scope boundaries of the window in which they are typed. One can cross scope boundaries in order to evaluate an expression with the syntax { expression } function-name. This, for example, is useful for using the globals window to look at static variables that are local to a function without having to open up a stack frame window. .IP "" Type casting may only be done through the use of the menu. .IP "" The following is not supported by dmdpi: ++ -- ?: op= string. .IP "" NOTE: expressions are always evaluated internally with a 32-bit precision. Therefore, results may not correspond in all cases with those generated by a C program. .P Expressions are also used to specify the condition in the conditional breakpoint. Note that the C comma operator is very useful in specifying the condition. Expressions separated by a comma are evaluated left-to-right and all but the rightmost expression are discarded. For example, a condition of \fI(x,y,x==y)\fR evaluates all three expressions; however, only the last expression (x==y) determines the result of the overall condition. The result is that the values of x and y are printed but execution halts only when x==y. .P Registers in the stack frame windows are prefixed with the character .B $ , for example, .B $d0. The address of a register is the location at which it was saved. Register values are only available after execution has been halted at a breakpoint or after a step. The exception to this rule is that one may look at register variables in calling functions if they happened to be saved in the called function. .P An expression may be made .I spy, in order to observe changes in the expression. The value of a spy expression is evaluated and displayed each time the debugger looks at the process, i.e., when the process calls wait() or sleep(). If the value of a spy changes, the expression is updated and a message is given that the expression has changed. If a conditional breakpoint (or trace on) is set, then the process will be halted. The option .B changed spies in the button 2 menu will manually force all spies to be re-evaluated. .P A maximum of 150 global variables will fit into the globals menu. If the targeted program has more than 150 global variables, the remaining variables must be accessed by typing their name from the keyboard. .RE .SK .TP .B Raw Memory Window The raw memory window is a ``memory editor'' in which memory is viewed as a sequence of 1-, 2-, 4- or 8-byte cells. The .B '.' operator is a special symbol which denotes a cell address. Therefore, commands such as .B .+1 in the button 2 menu give the next increment of memory after the current cell address. The keyboard command .B .= displays the cell with address equal to expression. The expression syntax is the same as defined above. The format of the displayed memory cells is .I x/y: , where x is the cell address, and y is the viewing increment. .RS Some of the functions available are: .RS .TP change cell size and display format Use the \fBsize\fR and \fBformat\fR items in the menu. .TP display cells above and below current cell. Use the \fB.[+-]\fR options in the menu. .TP indirect to cell Look at the cell using the contents of the current cell as an address. Use the .B \(** thru . option. .TP change cell value This is done with the keyboard expression: .B $= .TP spy on memory cell If the memory contents change, dmdpi will give notification. .TP disassemble instruction at cell. Display the assembler instruction in the assembler window. Use the .B asmblr option in the button 2 menu. .RE .RE .TP .B (Dis)Assembler Window Allows viewing of memory as a sequence of assembler instructions. The menu options of this window are similar to those in the source text window. The difference is that this window deals with assembler instructions rather than the high-level source code. .RS .P An instruction at a certain address can be displayed by entering the keyboard expression .B .=. The expression syntax is the same as defined above. More instructions can be viewed in a sequential manner using the .B next options in the button 2 menu. The next 1, 5, or 10 instructions starting from the current instruction can be displayed. .P When setting a breakpoint or stepping into an assembler function, one must step through the link and the movm.l instructions before \fIdmdpi\fR will be able to generate the stack frame for the function. .P Some of the other functions available are: .RS .TP change display format .TP open a stack frame window for instruction's function .TP display instruction as cells in the raw memory window .TP set/clear breakpoint on instruction .TP open stack frame window for instruction's function .TP display instruction at current PC .TP single step instruction(s) .RE .RE .TP .B User Types Window Shows user-defined types and allows the display format of user-defined types displayed in the globals and stack frame windows to be changed. For example, the display format of a structure may be changed so that certain fields are not displayed (hidden) and other fields are displayed (shown). .TP .B Journal Window Keeps a log of significant events in the course of a debugging session. .TP .B Breakpoint List Window Lists all active source and assembler breakpoints. Allows clearing of specified breakpoints or all breakpoints. .RS .P Functions available include: .RS .TP show source or assembler line at which a breakpoint is set .TP clear a single breakpoint .TP clear all breakpoints .SH SEE ALSO .PP dmdcc(1), dmdld(1), ucache(1). .SH WARNINGS Do not use the -O optimizer option of dmdcc when compiling a program to be debugged with dmdpi. This will confuse dmdpi. .P It is possible to receive a message that there is no more memory on the host system. This will happen if the process you are debugging has a very large symbol table, or if you are debugging many processes at the same time. The maximum amount of memory that a UNIX process is allowed to consume can be changed by a system administrator. For a 3B2 host computer running System V Release 2.0, how to change the per process memory limit is documented in the manual \f2AT&T 3B2 Computer Unix System V Release 2.0 System Administration Utilities Guide\f1 in the chapter "Administrative Tasks" under "Tunable Parameters." An alternative to changing the host computer's per process memory limit is to use the \fImc68cprs\fR CCS utility to compress the size of process symbol tables before they are opened for debugging with dmdpi. .SH BUGS In switch statements there is no boundary between the last case and the branch code; the program .I appears to jump to the last case (but is really in the branch) and then to the real case. .P The structure P which is of type "struct Proc \(**" within applications is interpreted by \fIdmdpi\fR as "struct proc". This implies that one must type P.state rather than P->state when accessing the structure P from the keyboard. .P If a program contains multiple global structure declarations of the same name, dmdpi will ignore all but the first declaration. .P A breakpoint cannot be set on a goto or return statement. Attempting to do so will set a breakpoint on the following line. Also, stepping onto a goto or return statement will execute the goto or return instead of stopping on the line. .P When stepping past an if statement that is the last statement within a while loop and the if condition fails and does not have an else condition, the program will appear to jump to the last line within the if statement. It is really jumping to the statement that will branch back to the top of the while loop.