![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to dmdpi.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / 630 / man / src / u_man / man1|
Return to dmdpi.1 CVS log | Up to [Research Unix] / researchv10dc / 630 / man / src / u_man / man1 |
1.1 root 1: .TH DMDPI 1 "630 MTG"
2: .SH NAME
3: dmdpi \- 630 MTG process inspector and debugger
4: .SH SYNOPSIS
5: .B dmdpi [ -c ]
6: .SH DESCRIPTION
7: .I Dmdpi
8: is a C language debugger that is bound dynamically to multiple subject
9: processes executing in a 630 MTG window in the layers environment.
10: In order to use dmdpi to its full capabilities, it is necessary to compile
11: the source program with the
12: .I -g
13: option of
14: .IR dmdcc .
15: However, if the target program is not compiled with
16: .I -g,
17: or no symbol tables
18: at all are available, dmdpi works as well as possible with the information
19: provided to it.
20: .PP
21: If the -c option is selected, \f2dmdpi\f1 will be
22: cached in the 630 MTG cache system. This will enable
23: \f2dmdpi\f1 to be executed again without the need for another
24: download.
25: .PP
26: Dmdpi uses a
27: multi-window user interface.
28: There are three types of windows:
29: debugger control windows,
30: which access the global state of the debugger;
31: process control windows (exactly one per process),
32: which start and stop processes and connect to process-specific functions;
33: and process inspection windows,
34: which include viewers for source text and memory, formatted various ways.
35: Initially, there are three debugger control
36: windows available: \fBdmdpi\fR, \fBhelp\fR
37: and \fBpwd/cd\fR.
38: .P
39: One might need to debug some initialization code that would ordinarily be
40: executed before dmdpi has a chance to gain control of the process.
41: The \fI-z\fR
42: of \fIdmdld\fR is useful for this purpose. This allows you to take
43: control of a process before the first statement is executed.
44: See the \fIdmdld(1)\fR manual page for details on using this option.
45:
46: .SS User Interface
47: Button 1 points.
48: Pointing at a window makes it current, noted with a highlighted border;
49: pointing at a line of text makes it current and inverts its video.
50: A scroll bar at the left of each window shows how
51: much of the text of a window is visible;
52: pointing into the scroll region and moving the mouse
53: controls what text is displayed.
54: .PP
55: Button 2 has a menu of operations that apply to the current line.
56: Operations above the
57: .B ~~~~~
58: separator are specific to each line;
59: operations below the separator are generic line operations:
60: .TP 1i
61: .B cut
62: Remove the line.
63: .TP
64: .B sever
65: Remove the line and all lines above it.
66: .TP
67: .B fold
68: Wrap the line, if it extends past the right margin.
69: .TP
70: .B truncate
71: Truncate the line at the right margin.
72: .LP
73: Button 3 has a menu of window-level operations and is in two parts.
74: Operations above the separator are specific to each window.
75: Operations below the separator are the following generic window operations:
76: .TP 1i
77: .B reshape
78: Change the size of a window.
79: .TP
80: .B move
81: Move a window to a different place.
82: .TP
83: .B close
84: Delete a window.
85: .TP
86: .B fold
87: Like button 2 fold above except it applies to all lines in the window.
88: .TP
89: .B truncate
90: Like button 2 truncate above except it applies to all lines in the window.
91: .TP
92: .B top
93: The sub-menu off the \fBtop\fR
94: is a list of windows;
95: selecting one makes it top and current.
96: .LP
97: Button 3 also is also used to sweep out new windows.
98: .PP
99: Keyboard characters accumulate at the bottom of the window.
100: If the current line accepts input, it flashes with each keystroke;
101: otherwise, if the current window accepts input, its border flashes.
102: Carriage return is ignored until a line or window
103: accepts the text, whereupon
104: the input line is sent to the line or window.
105: .PP
106: The following keyboard commands are also available:
107: .TP
108: .B "\'>file\'"
109: This saves the contents of the current line, or current window if there is
110: no current line, into the named file. To achieve the status of no current line
111: in the window, scroll off the top or bottom of the window.
112: .TP
113: .B "\'<file\'"
114: Each line of the named file is sent to the line or window as though it had
115: come from the keyboard.
116: .TP
117: .B ?
118: Each line or window that accepts keyboard input produces
119: some help in response to
120: .BR ? .
121: These messages specify the format of what may be typed.
122: Items in brackets ([]) are optional parameters in the keyboard input expression.
123: Explanations are contained within braces ({}).
124:
125: .PP
126: Special cursor icons occasionally appear:
127: .TP
128: .B arrow-dot-dot-dot
129: The host is completing an operation; the terminal is ready
130: asynchronously.
131: .TP
132: .B coffee cup
133: The terminal is receiving input from the host; the terminal momentarily is blocked.
134: .TP
135: .B exclamation mark
136: Confirm a dangerous menu selection by pressing that menu's button again.
137:
138: .SS Debugger Control Windows
139: .TP
140: .B Dmdpi Window
141: The most important debugger control window is the dmdpi window, which is
142: the first window created after the debugger downloads.
143: Each line within the dmdpi window refers to a specific process running
144: in the terminal.
145: A process is identified by its 630 MTG process table address.
146: Along with each process is a path to
147: its host resident download module (argv[0]).
148: This pathname is used by dmdpi to find the symbol table and debugger
149: information for the process.
150: .RS
151: .P
152: Lines may be introduced to the dmdpi window by running
153: .I list processes
154: from the button 3 menu or by typing a process table address and symbol
155: table path from the keyboard.
156: Typing the information at the keyboard may be useful if one wishes to
157: change the pathname of where the process symbol table might be found.
158: .P
159: Lines are also introduced into the dmdpi window when opening
160: or closing a process control window for a process which is
161: currently not listed in the dmdpi window.
162: .P
163: Note that the list of processes in the dmdpi window is not
164: dynamically updated as new processes are created or deleted,
165: or when application programs exit. This can lead to invalid
166: processes being listed in the dmdpi window until list
167: processes is again chosen from the button 3 menu.
168: .RE
169:
170: .TP
171: .B Pwd/cd Window
172: The pwd/cd window controls
173: the working directory of the debugger.
174: The initial working directory is the directory in which dmdpi is executed.
175: The working directory can be changed either by typing a path from the keyboard
176: or by selecting directory listings in button 2 and button 3 menus.
177:
178:
179: .TP
180: .B Help Window
181: The help window contains a reminder of user interface mechanics.
182:
183: .SS Process Control Windows
184: A process control window is created from the dmdpi window in
185: one of two ways.
186: .I Open process
187: on the button 2 menu opens the process currently highlighted in the dmdpi
188: window.
189: .I Pick process
190: on the button 3 menu causes the mouse cursor to change to a target cursor
191: which can be used to point to a window containing a process to debug.
192: .PP
193: The paths to symbol tables shown in the dmdpi window is not a full path
194: name if the location of the host resident download module for the program
195: being debugged is specified to \fIdmdld\fR as a relative path name. If
196: this is the case, the debugger is not able to find symbol tables
197: unless the working directory of the debugger is the same as the
198: directory in which the application was downloaded. If symbol tables cannot be
199: found, close the process window, change the working directory of the
200: debugger from the pwd/cd window, and then reopen the process window.
201: .PP
202: A process control window indicates the process's state
203: and shows the call stack traceback if the process is halted or dead.
204: The call stack is the dynamic chain of activation records.
205: The process control window also
206: connects to process inspection windows that access source text,
207: local variables within a stack frame,
208: raw memory, and so on.
209: These windows are cross-connected; so, for example,
210: an instruction in a process's assembly language window can
211: be inspected as a hexadecimal opcode in the raw memory window.
212: Closing the process control window closes all the process inspection
213: windows associated with it.
214: .PP
215: States are:
216: .TP 1.5i
217: .PD 0
218: .SM
219: .B RUNNING
220: running normally
221: .TP
222: .SM
223: .B STOPPED
224: stopped asynchronously by the debugger
225: .TP
226: .SM
227: .B BREAKPOINT
228: halted on reaching breakpoint
229: .TP
230: .SM
231: .B STMT STEPPED
232: halted after executing C source statement(s)
233: .TP
234: .SM
235: .B INSTR STEPPED
236: halted after executing machine instruction(s)
237: .TP
238: .SM
239: .B PROCEESS EXCEPTION
240: a process exception has occurred
241: .TP
242: .SM
243: .B ERROR STATE
244: the process has probably exited.
245: .PD
246: .LP
247: When in the \fBRUNNING\fR state, the status of selected bits of the P->state
248: variable is displayed and updated.
249: .PP
250: The menu operations on the process are:
251: .TP 1i
252: .PD 0
253: .B run
254: let the process run
255: .TP
256: .B stop
257: stop the process
258: .TP
259: .B src text
260: open source text window(s)
261: .TP
262: .B Globals
263: open window for evaluating expressions in global scope
264: .TP
265: .B RawMemory
266: open window for editing uninterpreted memory
267: .TP
268: .B Assembler
269: open window for disassembler
270: .TP
271: .B User Types
272: open window for setting user types
273: .TP
274: .B Journal
275: open debugging session journal window
276: .TP
277: .B Bpt List
278: open breakpoint list window
279: .PD
280: .LP
281: Each line of the call stack traceback describes one function.
282: Each function in the traceback can open a stack frame
283: expression evaluator window
284: or display its current source line.
285:
286: .SS Process Inspection Windows
287: .TP
288: .B Source Text Windows
289: The source text window contains a listing of a source file. If there is more
290: than one source file for the process, selecting the
291: .B src text
292: item in the process control window will give you a source files window
293: in which there is a listing of all the source files associated with that
294: process. Library function source files are included in this list, even
295: though one might not actually have the source for these functions.
296: By highlighting a source line and selecting
297: .B open source file
298: in the button 2 menu, you can open a source listing for that file.
299: Each source file is in a separate window, which can be opened when needed.
300: The source files are searched for in the working directory.
301: Entering a pathname from the keyboard (when the Source files window is
302: current) enters a pathname prefix which points to a directory
303: where the source can be found, without changing the working directory.
304: .RS
305: .P
306: When opening a source file,
307: dmdpi
308: checks to see whether the source file is in time sync with the object module.
309: If not, dmdpi gives a message of this fact. One may override this
310: condition with the
311: .B reopen
312: item in the button 3 menu of the source text window.
313: Source lines are displayed on a "per request basis." In other words, only
314: the lines that are currently visible are sent from the host. More lines
315: are sent to be displayed on the terminal as needed.
316: .P
317: Specific strings may be searched for in the source text by
318: using \fI/string\fR, or the \fI?string\fR entered at the
319: keyboard, for searching forward and backward in the source
320: text respectively. The search will begin at the next (previous
321: for backwards search) C language statement rather than at the
322: next source line. Note that repeated reverse searches for the
323: same pattern must be specified as \fI??\fR rather than \fI?\fR
324: due to a conflict with the help operator (?).
325: Line numbers can also be searched
326: for by entering a line number at the keyboard when a line is not current
327: within the window. If a line is current, the number is evaluated as
328: a constant expression (see expressions below). To achieve the
329: status of no current line, scroll the current line off the top or bottom of
330: the window.
331: .P
332: .B Breakpoints
333: are set on source lines. A breakpoint is set by highlighting
334: the line on which you wish to break execution and selecting
335: .B set bpt
336: from the button 2 menu.
337: A breakpoint is denoted by a '>>>' next to the source line.
338: When the process reaches this line the process
339: halts and will not execute the line on which the breakpoint is set.
340: Clearing the breakpoint is done by highlighting the line on which a breakpoint
341: is set and selecting
342: .B clear bpt
343: from the button 2 menu. Clearing the breakpoint can also be done from the
344: breakpoint list
345: window (see below). A
346: .B conditional breakpoint
347: is a breakpoint that is set with a certain condition. When this condition
348: evaluates to TRUE, the process is halted.
349: Any valid dmdpi expression may be used as a condition
350: (see keyboard expressions).
351: To set a conditional breakpoint, select
352: .B cond bpt
353: from the button 2 menu. You are prompted to enter an expression
354: from the keyboard as a condition.
355: An example of a condition would be (x==1). When the variable x becomes
356: equal to 1, then execution breaks. The
357: .B trace on
358: item in the button 2 menu is actually a conditional breakpoint with
359: the condition of 0, meaning that the condition never evaluates to TRUE.
360: This has the effect of tracing a statement but never breaking execution.
361: The conditional breakpoint is removed in the same way a
362: regular breakpoint is removed.
363: .P
364: Once the process has been halted, select \f3run\f1 to start the process running again.
365: You can also
366: .B step
367: (execute) a number of source lines and then stop
368: again after these statements have been executed.
369: When statements are stepped, the debugger will not enter functions
370: unless the
371: .B step into fcn
372: item is actually specified. The current statement can always
373: be seen by selecting
374: the
375: .B current stmt
376: item in the button 3 menu. This highlights the statement currently in the PC.
377: .P
378: Another option that is available in the source text window is the ability
379: to look at the assembly code for a specified line. Highlighting a line and
380: selecting
381: .B assembler
382: in the button 2 menu displays the first assembler instruction of the
383: statement.
384: .RE
385:
386: .TP
387: .B Globals and Stack Frame Windows
388: A stack frame window is opened from a line in the call stack traceback
389: in the process control window or
390: from a line of source text. A globals window is opened from the button 3 menu
391: in the process control window.
392: These windows evaluate expressions with respect to global scope,
393: and scope in a function, respectively.
394: .RS
395: .P
396: .B "Expressions"
397: .P
398: Expressions may be entered from the keyboard or with the mouse.
399: The syntax for expressions in dmdpi is the same as C language expressions,
400: except for differences noted below.
401: The expressions are most commonly used for inspecting values of variables in
402: the program that is being debugged.
403: An example of an expression is
404: .I r.origin.x.
405: This
406: may be typed in order
407: to inspect the x coordinate value of a rectangle origin point if the process
408: has a rectangle
409: .I r.
410: .P
411: A summary of dmdpi's expression syntax is presented here only to
412: aid comprehension, rather than an exact statement of the language.
413: .RE
414: .sp
415: .RS
416: \fI
417: expression :
418: constant
419: primary
420: \(**expression
421: &expression
422: -expression
423: !expression
424: ~expression
425: sizeof expression
426: typeof expression
427: fabs (expression)
428: (type-name) expression /\(** from menu only \(**/
429: {expression} identifier
430: expression binop expression
431: expression = expression
432: expression , expression
433:
434:
435: primary:
436: $
437: identifier
438: ( expression )
439: primary ( [expression-list] )
440: primary[ expression ]
441: lvalue.identifier
442: primary -> identifier
443:
444: lvalue:
445: identifier
446: primary[expression]
447: lvalue.identifier
448: primary -> identifier
449: \(**expression
450: (lvalue)
451:
452: binop:
453: \(** / % + - >> << < > <= >= == != & ^
454: | && ||
455: \fR
456: .P
457: The major differences in the expressions which dmdpi understands and
458: the C expressions are:
459: .IP ""
460: The unary operators \fIfabs\fR and \fItypeof\fR are supported.
461: .I fabs
462: evaluates the absolute value of a floating point number.
463: .I typeof
464: evaluates the type of an expression.
465: Examples are:
466: .br
467: fabs(-2.0)=2
468: .br
469: typeof(r.origin)= struct Point
470: .IP ""
471: The concept of a "current expression" has been introduced with the
472: .B $
473: operator.
474: .B $
475: is equal to the current highlighted expression. For example, if the line
476: containing \fIr.origin\fR is highlighted, one may type
477: .B $.x
478: to see the value of the x coordinate.
479: Another example of the
480: .B $
481: expression is
482: .B $=<expression>.
483: This can be used, for instance if
484: .B $
485: is equal to a variable x and you wish
486: to change the value of x to <expression>.
487: .IP ""
488: Expressions are evaluated within the scope boundaries of the window in
489: which they are typed. One can cross scope boundaries in order to evaluate
490: an expression with the syntax { expression } function-name.
491: This, for example, is useful for using the globals window to look
492: at static variables that are local
493: to a function
494: without having to open up a stack frame window.
495: .IP ""
496: Type casting may only be done through the use of the menu.
497: .IP ""
498: The following is not supported by dmdpi: ++ -- ?: op= string.
499: .IP ""
500: NOTE: expressions are always evaluated internally with a 32-bit precision.
501: Therefore,
502: results may not correspond in all cases with those generated by a C
503: program.
504: .P
505: Expressions are also used to specify the condition in the conditional
506: breakpoint. Note that the C comma operator is very useful in specifying
507: the condition.
508: Expressions separated by a comma are evaluated left-to-right and all but
509: the rightmost expression are discarded.
510: For example, a condition of \fI(x,y,x==y)\fR evaluates all
511: three expressions; however, only the last expression (x==y) determines
512: the result of the overall condition. The result is that the values of
513: x and y are printed but execution halts only when x==y.
514: .P
515: Registers in the stack frame windows are prefixed with the character
516: .B $
517: , for example,
518: .B $d0.
519: The address of a register is the location at which it was saved.
520: Register values are only available after execution has been halted
521: at a breakpoint or after a step. The exception to this rule is that
522: one may look at register variables in calling functions if they happened
523: to be saved in the called function.
524: .P
525: An expression may be made
526: .I spy,
527: in order to observe changes in the expression.
528: The value of a spy expression is evaluated and displayed
529: each time the debugger looks at the process, i.e., when the process calls
530: wait() or sleep().
531: If the value of a spy changes, the expression is updated and a message is
532: given that the expression has changed.
533: If a conditional breakpoint (or trace on) is set, then the process will be
534: halted.
535: The option
536: .B changed spies
537: in the button 2 menu will manually force all spies to be re-evaluated.
538: .P
539: A maximum of 150 global variables will fit into the globals menu. If
540: the targeted program has more than 150 global variables, the remaining
541: variables must be accessed by typing their name from the keyboard.
542: .RE
543: .SK
544: .TP
545: .B Raw Memory Window
546: The raw memory window is
547: a ``memory editor'' in which
548: memory is viewed as a sequence of 1-, 2-, 4- or 8-byte cells.
549: The
550: .B '.'
551: operator is a special symbol which denotes a cell address. Therefore, commands
552: such as
553: .B .+1
554: in the button 2 menu give the next increment of memory after the current
555: cell address. The keyboard command
556: .B .=<expression>
557: displays the cell with address equal to expression.
558: The expression syntax is the same as defined above.
559: The format of the displayed
560: memory cells is
561: .I x/y: <contents>,
562: where x is the cell address, and y is the viewing increment.
563: .RS
564: Some of the functions available are:
565: .RS
566: .TP
567: change cell size and display format
568: Use the \fBsize\fR and \fBformat\fR items in the menu.
569: .TP
570: display cells above and below current cell.
571: Use the \fB.[+-]<amount>\fR options in the menu.
572: .TP
573: indirect to cell
574: Look at the cell using the contents of the current cell as an address.
575: Use the
576: .B \(** thru .
577: option.
578: .TP
579: change cell value
580: This is done with the keyboard expression:
581: .B $=<expression>
582: .TP
583: spy on memory cell
584: If the memory contents change, dmdpi will give notification.
585: .TP
586: disassemble instruction at cell.
587: Display the assembler instruction in the assembler window. Use the
588: .B asmblr
589: option in the button 2 menu.
590: .RE
591: .RE
592: .TP
593: .B (Dis)Assembler Window
594: Allows viewing of memory as a sequence of assembler instructions.
595: The menu options of this window are similar to those in the source text
596: window. The difference is that this window deals with assembler instructions
597: rather than the high-level source code.
598: .RS
599: .P
600: An instruction at a certain address can be displayed by entering the
601: keyboard expression
602: .B .=<expression>.
603: The expression syntax is the same as defined above.
604: More instructions can be viewed in a sequential manner using the
605: .B next
606: options in the button 2 menu. The next 1, 5, or 10 instructions
607: starting from the current instruction can be displayed.
608: .P
609: When setting a breakpoint or stepping into an assembler function, one must
610: step through the link and the movm.l instructions before \fIdmdpi\fR will be
611: able to generate the stack frame for the function.
612: .P
613: Some of the other functions available are:
614: .RS
615: .TP
616: change display format
617: .TP
618: open a stack frame window for instruction's function
619: .TP
620: display instruction as cells in the raw memory window
621: .TP
622: set/clear breakpoint on instruction
623: .TP
624: open stack frame window for instruction's function
625: .TP
626: display instruction at current PC
627: .TP
628: single step instruction(s)
629: .RE
630: .RE
631: .TP
632: .B User Types Window
633: Shows user-defined types and allows the display format of user-defined
634: types displayed in the globals and stack frame windows to be changed.
635: For example, the display format of a structure may be changed so that
636: certain fields are not displayed (hidden) and other fields are displayed
637: (shown).
638: .TP
639: .B Journal Window
640: Keeps a log of significant events in the course of a debugging session.
641: .TP
642: .B Breakpoint List Window
643: Lists all active source and assembler breakpoints.
644: Allows clearing of specified breakpoints or all breakpoints.
645: .RS
646: .P
647: Functions available include:
648: .RS
649: .TP
650: show source or assembler line at which a breakpoint is set
651: .TP
652: clear a single breakpoint
653: .TP
654: clear all breakpoints
655: .SH SEE ALSO
656: .PP
657: dmdcc(1),
658: dmdld(1),
659: ucache(1).
660: .SH WARNINGS
661: Do not use the -O optimizer option of dmdcc when compiling a program
662: to be debugged with dmdpi.
663: This will confuse dmdpi.
664: .P
665: It is possible to receive a message that there is no more memory on the
666: host system. This will happen if the process you are debugging has a very
667: large symbol table, or if you are debugging many processes at the same time.
668: The maximum amount of memory that a UNIX process is allowed to consume
669: can be changed by a system administrator. For a 3B2 host computer running
670: System V Release 2.0, how to change the per process memory limit is
671: documented in the manual \f2AT&T 3B2 Computer Unix System V Release 2.0
672: System Administration Utilities Guide\f1 in the chapter
673: "Administrative Tasks" under "Tunable Parameters." An alternative to
674: changing the host computer's per process memory limit is to use
675: the \fImc68cprs\fR CCS utility to compress the size of process symbol tables
676: before they are opened for debugging with dmdpi.
677: .SH BUGS
678: In switch statements there is no boundary between the last case
679: and the branch code; the program
680: .I appears
681: to jump to the last case (but is really in the branch)
682: and then to the real case.
683: .P
684: The structure P which is of type "struct Proc \(**" within applications is
685: interpreted by \fIdmdpi\fR as "struct proc". This implies that one must
686: type P.state rather than P->state when accessing the structure P from the
687: keyboard.
688: .P
689: If a program contains multiple global structure declarations
690: of the same name, dmdpi will ignore all but the first declaration.
691: .P
692: A breakpoint cannot be set on a goto or return statement.
693: Attempting to do so will set a breakpoint on the following
694: line. Also, stepping onto a goto or return statement will
695: execute the goto or return instead of stopping on the line.
696: .P
697: When stepping past an if statement that is the
698: last statement within a while loop and the if condition fails
699: and does not have an else condition,
700: the program will appear to jump to the last line within the if
701: statement. It is really jumping to the statement that will
702: branch back to the top of the while loop.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.