build: Better Build System

1 files changed, 702 insertions, 0 deletions

diff --git a/static/unix-v10/man1/dmdpi.1 b/static/unix-v10/man1/dmdpi.1
new file mode 100755
index 00000000..aff5f198
--- /dev/null
+++ b/static/unix-v10/man1/dmdpi.1
@@ -0,0 +1,702 @@
+.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 "\'<file\'"
+Each line of the named file is sent to the line or window as though it had
+come from the keyboard.
+.TP
+.B ?
+Each line or window that accepts keyboard input produces
+some help in response to
+.BR ? .
+These messages specify the format of what may be typed.
+Items in brackets ([]) are optional parameters in the keyboard input expression.
+Explanations are contained within braces ({}).
+
+.PP
+Special cursor icons occasionally appear:
+.TP
+.B arrow-dot-dot-dot
+The host is completing an operation; the terminal is ready
+asynchronously.
+.TP
+.B coffee cup
+The terminal is receiving input from the host; the terminal momentarily is blocked.
+.TP
+.B exclamation mark
+Confirm a dangerous menu selection by pressing that menu's button again.
+
+.SS Debugger Control Windows
+.TP
+.B Dmdpi Window
+The most important debugger control window is the dmdpi window, which is
+the first window created after the debugger downloads.
+Each line within the dmdpi window refers to a specific process running
+in the terminal.
+A process is identified by its 630 MTG process table address. 
+Along with each process is  a path to
+its host resident download module (argv[0]).
+This pathname is used by dmdpi to find the symbol table and debugger 
+information for the process.
+.RS
+.P
+Lines may be introduced to the dmdpi window by running
+.I list processes
+from the button 3 menu or by typing a process table address and symbol
+table path from the keyboard.
+Typing the information at the keyboard may be useful if one wishes to 
+change the pathname of where the process symbol table might be found.
+.P
+Lines are also introduced into the dmdpi window when opening
+or closing a process control window for a process which is
+currently not listed in the dmdpi window.
+.P
+Note that the list of processes in the dmdpi window is not
+dynamically updated as new processes are created or deleted,
+or when application programs exit. This can lead to invalid
+processes being listed in the dmdpi window until list
+processes is again chosen from the button 3 menu.
+.RE
+
+.TP
+.B Pwd/cd Window
+The pwd/cd window controls
+the working directory of the debugger.
+The initial working directory is the directory in which dmdpi is executed.
+The working directory can be changed either by typing a path from the keyboard
+or by selecting directory listings in button 2 and button 3 menus.
+
+
+.TP
+.B Help Window
+The help window contains a reminder of user interface mechanics.
+
+.SS Process Control Windows
+A process control window is created from the dmdpi window in
+one of two ways.
+.I Open process
+on the button 2 menu opens the process currently highlighted in the dmdpi
+window.
+.I Pick process
+on the button 3 menu causes the mouse cursor to change to a target cursor
+which can be used to point to a window containing a process to debug.
+.PP
+The paths to symbol tables shown in the dmdpi window is not a full path
+name if the location of the host resident download module for the program
+being debugged is specified to \fIdmdld\fR as a relative path name. If
+this is the case, the debugger is not able to find symbol tables
+unless the working directory of the debugger is the same as the 
+directory in which the application was downloaded. If symbol tables cannot be
+found, close the process window, change the working directory of the
+debugger from the pwd/cd window, and then reopen the process window.
+.PP
+A process control window indicates the process's state
+and shows the call stack traceback if the process is halted or dead.
+The call stack is the dynamic chain of activation records.
+The process control window also
+connects to process inspection windows that access source text,
+local variables within a stack frame,
+raw memory, and so on.
+These windows are cross-connected; so, for example,
+an instruction in a process's assembly language window can
+be inspected as a hexadecimal opcode in the raw memory window.
+Closing the process control window closes all the process inspection 
+windows associated with it.
+.PP
+States are:
+.TP 1.5i
+.PD 0
+.SM
+.B RUNNING
+running normally
+.TP
+.SM
+.B STOPPED
+stopped asynchronously by the debugger
+.TP
+.SM
+.B BREAKPOINT
+halted on reaching breakpoint
+.TP
+.SM
+.B STMT STEPPED
+halted after executing C source statement(s)
+.TP
+.SM
+.B INSTR STEPPED
+halted after executing machine instruction(s)
+.TP
+.SM
+.B PROCEESS EXCEPTION
+a process exception has occurred
+.TP
+.SM
+.B ERROR STATE
+the process has probably exited.
+.PD
+.LP
+When in the \fBRUNNING\fR state, the status of selected bits of the P->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 $=<expression>.
+This can be used, for instance if
+.B $
+is equal to a variable x and you wish
+to change the value of x to <expression>.
+.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 .=<expression>
+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: <contents>, 
+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.[+-]<amount>\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 $=<expression>
+.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 .=<expression>.
+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.