.PH "'Notes on the D-MACHINE''1980'"
.PF "''- % -''"
.SA 1
.SK 0
.nr Hi 1
.nr Pt 1
.H 1 INTRODUCTION
The programs described in these notes are
for the translation and emulation of the
micro code "TRANSLANG". Translang is the
language used to produce micro code for the
micro programed computer called the D-MACHINE.
.P
The programs run on the Electrical Engineering
PDP-11 under the UNIX operating system.
.P
Before reading any further, the student should
read the notes on  "Introduction to UNIX"
and the notes on the "Text Editor".
.H 1 "PRODUCING THE PROGRAM"
To translate and run a micro program for
the D-MACHINE using the translator and
emulator, the program should be entered into
a file using the
Text Editor. This will make a permanent copy
which may be altered to correct errors or
to add improvements without having
to type the whole program again.
.H 2 "Creating the File"
The first step in producing the program is
to create a file with the appropriate text.
.P
After logging on to the computer\*F
.FS
See the Introduction to UNIX
.FE
you will receive a prompt '%'. This is to
tell the operator that commands may be
accepted. To start the editor, the command
"em filename" is issued. The filename part
is the name of the file in which the text
will be placed. The editor will respond with
the prompt '>' and text may be entered as
indicated in the editor notes.
.P
To carry out the example on page 93 of the
textbook "Microprograming Primer" in which
integer multiplication by repeated addition
is performed,
the following text would be entered. The underlined
text is the output from the computer.
The (cr) indicates that the return key should
be depressed at this point. It will be used
only in this example.
.DS
.in +10
_% em test(cr)
\fIEditor\fR
_>a(cr)
commnt This program performs integer multiplication
commnt by repeated addition.
init.(cr)
	lit r = a1,bad		$load 10 to b and(cr)
	10 = lit,1 = sar	$5 to a1(cr)
$	loop starts here(cr)
	test-1 = ampcr(cr)
	0 = a2, call		$branch to test(cr)
loop.(cr)
	a2+b = a2		$product in a2(cr)
test.(cr)
	a1-1 = a1(cr)
	if aov then jump	$back to loop(cr)
	end(cr)
\&.(cr)
_>w(cr)
\fI297\fR
_>q(cr)
_%
.in -10
.DE
.P
The file test now contains the text of the
program to be run. It will remain
in existence until it is removed. This file
may be used directly as input to the
translator.
.H 2 "Specifications for the Input Language"
The first thing to note are that there are
some differences between the reference
language described in the text book and the
input language for the translator.
.P
The input file must follow the specifications
if the program is to be accepted as a valid
program by the translator. 
.P
The specifications are:-
.VL 14 2
.LI Format
The input text must have one statement per
line. Blank lines between statements will
be ignored.
.LI Comments
A comment may be added into the text by using
the 'commnt' keyword on a new line, followed
by the comment. This text will be ignored.
.br
.SP
Another form of comment which is placed at
the end of a statement line is signified
by the '$' followed by the text of the
comment (see above example for comments).
.LI Labels
A program label is generated by the label
name followed by a '.' on the start of a
new line. A label name may consist of
alpha-numeric characters, with upper and lower
case considered distinct. The label
must not start with a digit and it may be
of any length although only the first 8
characters are significant.
.br
.SP
Labels should not be the same as keywords.
A list of keuwords may be found in appendix C.
.br
.SP
Labels may be at the start of a statement
line or on a line by themselves. More than
one label may be defined at any point by
separate labels on separate lines.
.LI "Separating Character"
.LI "\ "
A separating character is needed at any point
to separate the characters of a keyword or
number. Either the space, tab, or comma may
be used as the separating character.
.LI "Numbers"
Numbers may be entered in one of three radices
which are indicated by
the first character.
.P
`1'-`9' indicate that the number is a decimal, `0' that it is octal,
and `0x' it is hexadecimal. The characters `a'-`f' are the
higher order hexadecimal digits.
.LE
.H 1 "TRANSLATION OF THE MICROPROGRAM"
Now that the microprogram text has been
entered into a file it may be used as input
to the translator.
.P

The translator program is called `trans'.
Its function is to take the input file
and produce a file which contains a
hexadecimal number representation of the
D-Machine instructions. In effect the
translator is an assembler for Translang.
.P
Trans is invoked with optional flags and
optional input and output files.
.P
For example the command "trans tmp test"
below invokes the translator with the input file
test and output file tmp. There are no flags
altered.
.DS
.in +5
% trans tmp test
>>>>>>> TRANSLANG D-Machine Translator	UNSW	23 Oct 78
Input file is test.
   0	commnt This program performs integer multiplication
   0	commnt by repeated addition.
   0	init.
   0		lit r = a1,bad		$load 10 to b and
   1		10 = lit,1 = sar	$5 to a1
   2	$	loop starts here
   2		test-1 = ampcr
   3		0 = a2, call		$branch to test
   4	loop.
   4		a2+b = a2		$product in a2
   5	test.
   5		a1-1 = a1
   6		if aov then jump	$back to loop
   7		end

No errors detected.
% 
.in -5
.DE
.P
As can be seen above the translator produces
a listing  of the input file and an indication
of the errors that occured (in this case
none).
.P
The general form of the translator command
is:-
.DS
.in +10
trans [-flags] [+flags] [hexfile [inputfile]]
.in -10
.DE
.P
The input file is the program text and the
hexfile is the output file. All arguments
are optional, except that if
the input file is to be specified then the
hexfile must also be specified. If the input
file is missing then input is taken from
standard input.
.P
The command "trans < test" redirects the
file test to the standard input of the
translator.
It has the same effect as before exept that there
is no need to specify the hex output file.
This form of the command may be used
when testing for errors in the input file.
.DS
.sp 3
.in +5
% trans < test
>>>>>>> TRANSLANG D-Machine Translator	UNSW	23 Oct 78
   0	commnt This program performs integer multiplication
   0	commnt by repeated addition.
   0	init.
   0		lit r = a1,bad		$load 10 to b and
   1		10 = lit,1 = sar	$5 to a1
   2	$	loop starts here
   2		test-1 = ampcr
   3		0 = a2, call		$branch to test
   4	loop.
   4		a2+b = a2		$product in a2
   5	test.
   5		a1-1 = a1
   6		if aov then jump	$back to loop
   7		end

No errors detected.
% 
.in -5
.DE
.P
The redirection of input allows for the piping of
the output of a preprocessor to the input
of the translator. See a later section for
the preprocessor.
.P
The flags specify options to the translator.
They indicate various outputs which may be
produced for the examination of the programmer.
.P
They are:-
.VL 13 8
.LI b
A binary listing of the code is generated.
.LI h
A hex listing of the code is generated at
the end of the output.
.LI l
A source listing is produced.
.LI s
A listing of the symbols declared is produced
i.e. the program labels.

.LI a
All the above options are selected.
.LE
.P
The `l' flag is set by default and all others
are reset.
.P
If `-' is used the the flag is turned
off. Similarly `+' turns the flag on.
.P
It should be noted that the line numbers
generated in the listing are the numbers
corresponding to the micro code instructions
produced, but the error messages produced
use the numbers of the lines in the text file.
The error line numbers may be used directly
in the editor to find the erroneous line.
.H 1 "RUNNING THE PROGRAM"
Having translated the program and removed
all errors, the next step is to run the
program with the emulator.
.P
The emulator program is called `dmach' which
is an abreviation of `D-Machine'.
.P
To run the emulator in the default mode dmach
may be called without arguments and a
question and answer session will determine
where the program is to come from.
.P
For the test program used previously, which
has been translated as above with the output
on the file tmp, the command "dmach tmp"
will produce the following:-
.DS
.SP 3
% dmach tmp
 >>>>>>>> D MACHINE		UNSW 26 Oct 78.
Hex to be read from tmp
Do you REALLY want to type in the s-memory? y
Enter s-memory in blocks.
Starting address? 9999

End of simulation. Registers contain:

p(1) addr = 4    p(3) addr = 4   clock =    23
a1 =37777777777  a2 =       62   a3 =        0   b =        12
mir =       0    sar =       1   lit =      12   ctr =       0  ampcr =     3
br1 =       0    br2 =       0   mar =       0   bmar =      0  gc1=0   gc2=0
lc1=0   lc2=0    lc3=0   mst=0   lst=0   abt=0   aov=0   cov=0  sai=0   rdc=0

Dump of s-memory.
Output can be in decimal,hex,octal, or ascii.
Input is:
	starting address. (9999 terminates dump)
	finishing address.	and
	output mode. (first character)
Starting address? 9999
% 
.SP 3
.DE
Where no S-Memory is required it would be
easier to have a file with 9999 as the only
line to save the initial questions.
Such a file is used in the folowing
examples (called no-s).
In this
example there is no interaction with the
S-Memory so that the dump at the end of the
run was not necessary. The dump at the end
may be stopped with the flag "-n" in the
command line.
.DS
.SP 3
% dmach -n tmp no-s
 >>>>>>>> D MACHINE		UNSW 26 Oct 78.
Hex to be read from tmp
S memory to be read from no-s
Starting address 9999

End of simulation. Registers contain:
p(1) addr = 4   p(3) addr = 4  clock =    23
a1 =37777777777 a2 =       62  a3 =        0  b =        12
mir =       0   sar =       1  lit =      12  ctr =       0  ampcr =     3
br1 =       0   br2 =       0  mar =       0  bmar =      0  gc1=0   gc2=0
lc1=0   lc2=0   lc3=0   mst=0  lst=0   abt=0  aov=0   cov=0  sai=0   rdc=0

% 
.SP 3
.DE
.P
The purpose of a simulator is to enable ease
of debugging the program before the necessity
to run the program on the actual hardware.
The next section will describe the type of
debugging which may be carried out with the
simulator.
.H 2 "DEBUGGING"
Dmach may be called with a number of flags,
most of which are used for debugging purposes.
.P
The main forms of debugging information are
register dumps, address tracing, and break
points.
.P
.H 3 "Register Dumps"
Register dumps may be obtained by the setting
of the flag 'l' in the command line. This
by itself will produce dumps of the registers
for the whole program, producing vast amounts
of output. The '-rb' and '-re' switch on
and of the register dumps respectively,
allowing selected sections
of the program to be watched.
.H 3 "Tracing Mode"
Tracing is performed on addresses within
the microprogram. The flag '-t' in the command
line will produce a dump of the registers
at the time that the indicated microprogram
address was accessed. This may be used to
trace the entry into a routine without having
the registers dumped all the time.
.H 3 "Break Points"
A break point may be set at a point in the
microprogram which will cause the program
to stop and allow the S-Memory to be examined
and changed. The break point is set by the
flag '-b' in the command line.
.H 3 "Debugging Example"
This example will trace the registers from
instruction 4 to instruction 5 and trace
address 3. The command line to execute
this has the flag '-rb4' to start the
register dumps at instruction 4 and the flag
\&'-re5' to stop the register dump at
instruction 5. To select the type of register
dump the flag '-l01' will select the A and
B registers plus the address and clock to
be dumped. To set the tracing on address
3 the flag '-t3' is used.
See appendix A for more detail.
.DS
.SP 3
% dmach -rb4 -re5 -l10 -t3 -n tmp no-s
 >>>>>>>> D MACHINE      UNSW 26 Oct 78.
Hex to be read from tmp
S memory to be read from no-s
Starting address 9999
p(1) addr = 3   p(3) addr = 0   clock =     4
a1 =        5   a2 =        0   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 3   clock =     5
a1 =        5   a2 =        0   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =     7
a1 =        4   a2 =        0   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 4   clock =     8
a1 =        4   a2 =       12   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =    10
a1 =        3   a2 =       12   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 4   clock =    11
a1 =        3   a2 =       24   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =    13
a1 =        2   a2 =       24   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 4   clock =    14
a1 =        2   a2 =       36   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =    16
a1 =        1   a2 =       36   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 4   clock =    17
a1 =        1   a2 =       50   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =    19
a1 =        0   a2 =       50   a3 =        0   b =        12
p(1) addr = 5   p(3) addr = 4   clock =    20
a1 =        0   a2 =       62   a3 =        0   b =        12
p(1) addr = 4   p(3) addr = 6   clock =    22
a1 =37777777777 a2 =       62   a3 =        0   b =        12


End of simulation. Registers contain:

p(1) addr = 4   p(3) addr = 4   clock =    23
a1 =37777777777 a2 =       62   a3 =        0   b =        12
mir =       0   sar =       1   lit =      12   ctr =       0   ampcr =     3
br1 =       0   br2 =       0   mar =       0   bmar =      0   gc1=0   gc2=0
lc1=0   lc2=0   lc3=0   mst=0   lst=0   abt=0   aov=0   cov=0   sai=0   rdc=0
% 
.SP 3
.DE
.H 1 "Preprocessor"
Included in the set of programs is a
preprocessor which is used to simplify the
entry of message strings into a series of
literal assignments.
.P
The name of the preprocessor is `prep'.
.P
The preprocessor takes standard input and
passes the processed data to standard output
which may be then piped to the translator.
See the section on the translator for more
details.
.P
To initiate processing of the text a line
with '.a' is required by itself. This is
followed by any number of lines of text,
and terminated with a seperate line with
the characters '..'. The processed text
becomes literal assignments which may be
used by a printing routine similar to the
one found in the first main example of the
appendix E.
.P
An example of preprocessing in use by itself
is:-
.DS
.ti 10
prep <file
.DE
.H 1 "Input and Output"
Special instructions have been included to
enable the microprogram to read from and write to
the terminal. This is achieved with a device
read and device write instruction. These
are 'dr1', 'dr2' and 'dw1', 'dw2'.
The instructions work exactly the same way
as the read and write to S-Memory.
.P
When a read command is issued one word is
formed from the information from the terminal.
This information may consist of one number
or four ascii characters. Special mapping
is needed  to avoid confusion. If the ascii
string starts with a digit then a '\\' must
be used in front of it. A leading blank must
be escaped with a '\\'. To enter a '\\'
\&'\\\\' must be used.
.P
For output using the dw1 or dw2 instruction
the output conversion is selected by the
address supplied. The legal addresses are:-
.VL 8 2
.LI 0
Octal conversion
.LI 1
Decimal conversion
.LI 2
Hexadecimal conversion
.LI 3
Ascii conversion
.LE
.P
When numbers are to be written they will be
followed by a newline character, while the
ascii string conversion is not. In the ascii
conversion, control characters can be printed.
