Text preview for : D0_microprogManual.pdf part of xerox D0 microprogManual xerox dolphin D0_microprogManual.pdf



Back to : D0_microprogManual.pdf | Home

c
c
p DO Microprogrammer's Manual

Document: Unassigned
Date: 0ctober 1978

c Version: 2.0




E
c- This manual is intended to provide all necessary documentation for microprogramming a DO.
Familiarity with the DO Functional Specification is assumed. Ail comments should be
addressed to the editor via Laurel.



c
L-
c a




c Release Stage: draft/RELEASED/issued




c Approval:


c
[1
XEROX
c BUSINESS SYSTEMS
Sjsicr,i Develoyrrierit
Palo Alto, California


c-
c
c
TABLE OF CONTENTS


D MICROASSEMBLER MANUAL
O

1. Introduction 1
2. Assembly Procedures 1
3. Error Messages . 3
4. Debugging Microprograms 4
5. Comments and Conditional Assembly 4
6. Simplified Parsing Rules 5
7. Statements Controlling Assembly - 6 .
8. Integers - 7 -
9. REPEAT Statements 8
10. Parameters 9
11. Constants 9
12. SETTASK Statements 10
13. Assembliag Data for RM 10
14. Assembling Data Items in the Instruction Memory 11
15. RM & STK Clauses 12
16. ALU Clauses 12
17. Memory Referencing Instruction Statements 12
18. Branching 13
18.1, Branch Clauses 14
18.2. Dispatch Clauses 15
18,3. Placement Declarations 15

MICRO: MACHINEmINDEPENDENT MICROASSEMBLER

1. Introduction 17
2, Assembly Procedures 17
3. Error Messages 20
4. Assembly Listings 21
5. Cross Reference Listings 22
60 Comments and Conditional Assembiy 23
7. Statements 24
7J. Builtins 25
7.2. Defining Symbols 25
7.3, Tokens 27
7.4. Neutrals and Tails 28
7.5. Clause Evaluation 30
7.6. Treatment of Arguments 30
7.7. Undefined Symbols 31
7.7.11. Destination Addresses 32 - -
7.72. Octal Numbers 32 - -
7.7.3. Literals 32
8. Integers 32
9. Macros 33
10. Neutrals 34
11. Eields, Assignments, and Preassignrnents 34
12. Conditionals 35
13. Memories, Addresses, and Stores 35
13.1. Target Memory 37
13.2, Default Statement 37
13.3. Post Macros 37
14. Repeat Statement 37
15. SELECT 38
16. Bit Tables 38
Appendix 1. Micro Error Messages 39
Appendix 2. Limitations of the Language 41
Appendix 3. Binary Output Format 44

MICROD MANUAL 46
D MICROPROGRAMMER'S GUIDE
O

1. Introduction 49
2. The ALU and Basic Architecture 49
2.1. Inputs and Outputs 49
2.2. The Stack 50
3. The Microinstruction and Branching Conditions
3.L The Microinstruction 51
3.2. Conditional Branches 51
3.3. Subroutine Calls 53
3.4. Dispatch 53 ~




. .
3.5. Changing Pages : : 53 .. , . , , - -
.
-
.. Notify
36 54
4. Special Functions 54
5. Memory and I/O
5.1. General Comments 56
5.2. Comnients on Style 56
b


.. Quadword Alignment
53 56
5.4. Bypassing 57
. . Memory Interlock
55 57
6. Getting Started 59
7. Caveats 60
8. Suggested Programming Style 60
9. Sample Programs 62
10. Common Error Messages 64

MIDAS MANUAL

1. Midas 65
2. Starting Midas 65
3. Midas Display 65
4. Midas Command Menu 67
Keyboard 69
5 a



6. Command Files 70 -3
-.


7. Syntax of Command-file Actions 72
8. Loading Programs 73
*


-1
-.



9. Dump and Compare 74
10a Virtual and Absolute Control Store Interpretation 74 -1
-.



lla Testing Directly From Midas 7s
12. Scope Loop Actions 77 -1
-.



D MIDAS MANUAL
O

- 1. Registers and Memories Known to Midas
2, TaskeSpecific Registers
3. Complications in the Display of Register Values
4. How Registers Are ReadIWritten
5. Special Keyboard Input Formats
6. STEP and GO
7a BREAK and UNBREAK *
8. BOOT
9. Acquiring Midas 82
10. Midas Maintenance 82 -1
-

D SIMULATOR MANUAL
O

1. Introduction 83
2. Documcntation 83 -1
-.



3. Getting Started 83
4. Using DDT 84 -1
-.

5. Load and Dump 84
6. Exaininc and Change 84 -1
-.


7. Simulator Execution 85
8. Command Strings 87 -1
-
9. DDT Conrniancls
10. The Simulator Memories 88
10.1. The C Memory in Detail 88
a
DO
MICROASSEMBLER
MANUAL

20 October 1978




Edward Fiala

edited by

Carol Hankins

Xerox Business Systems
Systems Development Department
3408 Hillview Road
Palo Alto, California 94304
DO Microassembler Manual 20 October 1978



r-
i
c,
1. Introduction
The D microprogramming language, called DOLang here, is implemented as a set of definitions on
O
'
top of the machine-independent assembler Micro. The assembly language is based upon the
machine description in the 30 July 77 release of "DO Processor Functional Specification".

If DOLang were perfect, you would never need to know any details of Micro itself--the language
specification described in this document would be complete. I have tried to make DOLang
complete, so if you are forced to modify or augment the DOLang definition file, please bring the
circumstances to my attention.
.
I In the event you are forced to fall back on basic Micro constructs, the docutnentation on Micro is
on-line. It is Micro.Press on M a c 1 < AltoDocs >. This is supplemented by
< AltoDocs > Micro.Tty.
The documentation here is also supposed to be complete, so you should not have to study the
DOLang definition file to figure out how anything works. If this proves untrue, please bring it to
my attention also.

All numbers in this document (and in DOLang source files) are in octal.

I personally write microprograms with the upper-case shift-lock key depressed, and the definitions
in the microlanguage consist entirely of upper-case characters. Howcver, a Micro switch converts all
source file characters to upper-case, so you may follow your own capitalization conventions and use
this switch.

Micro flushes Bravo trailers, so you can use Bravo formatting if you want to. Fiowcver, the cross
refcrcncc program, Mcross, which is expected to produce primary microprogram documentation,
!
I docs not handle Bravo trailers, so you are advised not to do any special formatting.



2. Assembly Procedures
To asscmble microprograms on your Alto, you must obtain from Maxc < Alto>Micro.run,
< DlSource > DOlangmc, and < Alto > MicroD.run. Micro, Micron, and DOLang may also be
obtaincd from Iris and Isis .

MICRO/L/E dOlang source1 source 2 ... sourceN

This caiiscs the soiircc files "dOlang.mc", "sourcel.mc", ..., "sourceN.mc" to be assembled. 'The
"/L" caiiscs a listing lilc named "sourccN.LS" to be produced. If "/Id" is omittcd, no listing file is
produced. The asscinbler also outputs "sourccN.I)II3i1*(intcnnediate binary and addresses),
"sourccN XR" (error tncssages--error tncssages go to thc termin:il irrespcctive of wlicther they are
also goiiig to thc .ER filc), and "sourceN.S?'" (the Micro symbol table after asscmblirig source N).
DO Illicroassernbler Manual 20 October 1978



I
I
In other words, micro assembles a sequence of source files with default extension "MC" and
I outputs four files whose extensions are ".DIB", ".ER", ".LS", and ".ST".The default name for
these is the name of the last source file to be assembled. Direct output to particular files as follows:

MICRO SYS/L SYS/B dOlang source 1 ... sourceN

This would cause listing output to be put on "SYS.LS" and symbol table and binary output on
"SYS.ST" and "SYS.DiB".

A summary of the local and global flags for Micro is as follows:

Global: /L Produces an expanded listing of the input
/N Suppresses binary and symbol table output
/U Convert text in all source filcs to upper-case
/O Omit .ST file

h l : /R Recover f o symbol table file
rm
/L Put expanded listing on named file
/B Put binary output and symbol table output on named file with extensions . I and
DB .T
S,
respectively. Default error listing to named file.
/E Put error listing on named file
/S Put symbol table on named file
/U Convert text in named file to upper-case

Assemblies are slow--it should take about 3 minutes to assemble a 2048-instruction microprogram.

The symbol table (.ST) produced by Micro can be uscd to establish a basis point for hrther
file
assemblies, thcrcby reducing assembly time. For example, you can build a DOLANG.ST file as
follows:

Micro dOlang

Then do all further assemblies as follows:

Micro/O dOlang/R sys/B source1 ... sourceN
MicroD dOLang sys


Prcassembling DOLANG in this way would save about 5 seconds of assembly -time. This time
savings is so small that I recommend you do not do it.

INSERT[file] stakments, as described in Section 2.7, can be put in source files so you don't have to
type as many source files on the command line.

AAcr obtaining an error-frec asscmbly from Micro, you must postprocess thc .DID file with MicroD
to transform it appropriately for loading by Midas. This is accomplished by the following command
linc syntax to thc Alto Executive:

MICROD SYS




2
DO Microassembler Manual 20 October 1978



The source files for MicroD (only SYS in the above example) are the output files produced by
Micro.

MicroD displays a progress message while it is churning away. I believe that MicroD will require
about 3 minutes to process a 2048-instruction file.

The output of MicroD is an ".MB" consisting of blocks of data that can be loaded into various
file,
D memories and of addresses associated with particular locations in memories. The memories are
O
as follows:

* IM 40-bit x 4000-word or 10000-word instruction memory
(also contains 20 bits/word of placement and other information)
.
RM 20-bit x 400-word register bank and stack memory


There are at present no facilities provided for microcode overlays. Providing such a facility would
require a major addition to MicroD and no such facility will be provided for a long time (maybe
never).



3. Error Messages
During assembly, error messages are output to both the display and the error file.

The "TITLE" statement in each source file causes an error message of the form:

l...title...JLC = 341


This message is not the rcsult of an error. It simply indicates that the assembler has started working
on that source file. "ILG=341" indicates that the first IM location asscmbled in this source file is
the 341st in the microprogram. This will be helpfbl in correlating sources statements with error
messages from the postprocessor, MicroD.

Micro error messages are in one of two forms, like the following:

218...error message
TAG + 39...error message


The first example indicates an error on 'the 218th ine of the sourcc file. This form is used for
errors that preccdc the first labcl in thc file. Thc sccond form is uscd afterwards, indicating an
error on the 39th linc afler thc label "TAG".

The most common error messages during asscmbly arc due to multiply sct ficlds in instructions and
to undefiticd symbols. I do not bclicvc that you will have any troublc figuring out that these
messages mean, so no coinmcnts arc offered licrc. 'llie Micro error mcssages arc discussed in
Scction 3.




3
I

DO 1ficroassernbler Manual
1 20 October 1978



MicroD error messages are discussed in Appendix A.



4, Debugging Microprograms
There is a simulator for the DO. See the section on Simulator.

Microprograms can also be debugged on the hardware using facilities provided by Midas. See the
section on Midas.

Midas facilities consist of a number of hardware tests, a loader for D microprograms, setlclear
O
breakpoints, start, step, or halt tlie machine, and examine and modify storage. Addresses defined
during assembly may be examined on the display.

Midas works with both the imaginary IM addresses defined in your source program and with the
absolute IM addresses assigned to instructions by MicroD. The way this works is discussed in the
Midas section.



5. Comments and Conditional Assembly
Micro ignores all non-printing characters and Bravo trailers. This means that you can freely use
spaccs, tabs, and carriage returns to format your file for readability without in any way affecting the
meaning of the statements.

4 Comments are handled as follows:

"*" begins a comment terminated by carriage return.
"%" begins a comment terminated by the next %'*. This is used for multi-line comments.

";'* tcrminates a statement. Note that if you omit tlie ";" terminating a statcment, and, for example,
put a "*" to begin a cuminerit, the same statement will be continued on the next line.

Micro has onc method of producing multi-statement conditional assemblies. This is the
COMME"T'CHA1~ feature, used as follows. , Suppose you want to h a w conditional assemblies
bascd on whether thc microcodc is being assumblcti for a 2K o r 4K D configtirtltioii. To do this
O
define "-" as the comment charxtcr for 2K (ix.,C'OMMEN'I'CHf~l~[-];) "!" as the cornrncnt
character for 4K. Then in the source files:
and


*! 2K configuration only
...statcmcnts For 2K cotifiguration...
*! end of 2K condiliorial
*- 4K configuration only
...statcmunts for 4K configuration...
*
,




4
DO Micronssenibler Manual 20 October 1978



In other words, "*" followed by the comment character is equivalent to "%" and is terminated by
its next occurrence.



6. Simplified Parsing Rules
After comments, false conditionals, and non-printing characters are stripped out, the rest of the text
forms STATEMENTS.

Statements are terminated by '*;'*. You can have as many staterncnts as you want on a text line,
and you can spread statements over as many text lines as you want. Statements may be indefinitely
long.

However, the size of Micro's statement buffer limits statemcnts to 500-decimal characters at any one
time. If this is exceeded at any time during the assembly of a statemcnt, an error message is
output. If you ever experience a statement buffer overflow error, please tell me. This should be
impossible except on multi-statement REPEATS.

The special characters in statements are:

T*and *199
for enclosing built-in, macro, field, memory, and address argument lists:
"(",,and'*)" for causing nested evaluation:
'* t as the final character of the token to its left:
, I , I,
to put the addrcss to its left into the symbol table w t value equal to the current
ih
location and current memory:
*I ,:
I f
scparates clauses or arguments
I,. I1
9 scparates staletnents
" #" #l. #2. etc., are the formal parameters insidc macro definitions
"01234567" are numbcr components (all arithmetic in octal)

All other printing Characters arc ordinary symbol constituciits, SO it is pcrfcctly ok to have symbols
containing + ", "-", "&", ctc., which would be syntactically significant in other languagcs. Also,
"

don't forget tliat blanks, carriage returns, and tabs arc syntactically rnwningless ( flushcd by the
prescan), so "P+Q" = "P + Q", each of which is a singlc symbol.

Notc that namc length is limited only by the size of the statcment buffer. However, avoid defining
addresses longer than 13 characters bccausc of problems you will encounter with thc dcbugger
Midas.

Statements arc divided into CI AUSES soparatcd by commas, and the clauscs arc cvaluatcd riglit-to-
left. An indefinite numbcr of cl;iuscs may appear it1 a statement.

Examples of clauses are:

i

P t- Q t 1 is referred to as a "soiircc while FOOt,
Fool+, and F002+ arc "dcstinatiotis" or "sinks".
+--
DO illicroassenibler iC.lantta1 20 October 1978

-1
-

PcSTEMP,
NAME[Nl[N2[ARG]],ARG2] FOO(X1,
6
--1
-.

Further discussion about clause evaluation is postponed until later.
-I
-_


7. Statements Controlling Assembly
b c h source file should begin with a TITLE statement as follows:

TITLE[SOURCEl];


The TITLE statement performs a number of operations.

a. It prints a message in the .ER file and on &hedisplay which will help you correlate subsequent
error messages with source statements which caused them.

b. It puts the assembler in TASK 0 mode and SUBROUTINE mode. These modes will be
discussed later.

The final file to be assembled should be terminated with an END statement:

END:


Currently, thc END stat
-r cnt doesn't do anything, but I might find something for it to do later.

You may at any place in the program include an INSERT statement:

INSERT[sourceX];


This is equivalent to the text of Ihc file sourceX.MC. Howevcr, since INSERT is defined by
I3OI.ANG, you cannot INSERT DOLANG itself--either DO1ANG itsclf or a /R file which
asscinblcd DOLANG must be explicitly mentioned on the command line or an INSERT function
must be defined in the file such as:

BUlLTlN[INSERT,24];
lNSERT[DOLANG);


Thc mcssagc printcd on the .ER file by TITLE is most helphl in corrclating subscqucnt crror
messages if any INSER'I' statements occur either bctbre the 'ITl'[,E statcmcnt or at the end of the
file (bcfure the END statctnent). INSERT works ok anywhcre, but it might be hnrdcr to figure out
which tile suffered an error if you dcviate froin this reconimcndation.

In the cvcnt you rcqucst a listiris by putting "/I," in Lhc Micro command hic, the cxact stuff
printcd is dctermiticd by dwlarations that can bc put anywlicre in your program.
I
~ i
-


DO iI4icroasseni15ler Manual 20 October 1978
[-
I
,

DOLang selects verbose listing output. However, unless you are looking for an elusive assembly
problem, you will generally NOT want to print this listing. The listing produced by MicroD is the
normal listing file you will use during debugging.

If you want to modify the default listing control in DOLang for any reason, you can do this using
the LIST statement, as follows:

LIST[memory,mode] ;


where the "memory" may be any of the following:

IM 4000-word or 1oooO-word x 40-bit (+20-bit placement) instruction memory
RM 400-word x 20-bit register bank memory

and the mode, the "OR" of any of the following:

10 alphabetically-ordered list of address symbols
4 numerically-ordered list of address symbols
2 (TAG) FF4-3, JCNc4, etc. (list of field stores)
1 (TAG) nnnn nnnn nnnn (octal value printout)

NOTE: The listing output will be incorrcct in fields affected by forward references (i.e., rcferences
to as yet undefined addresses).



8. Integers
4
Micro provides a number of built-in operations for manipulating 20-bit assembly-time intcgers.
These have nothing to do with code generation or storage for any memorics. Integers are uscd to
irnplement assembly-time variablcs and to control REPEAT strttemcn1s. 'I'lie operations given in the
table below arc included here for cornpletencss, but hopefully you will nut have to use any of them
except SET:

SET[NAME,OCT] Defines NAME as an integer with value OCT. Changes the
value of NAME if already defined.
SELECT[i, CO, ... , Cn] i must be an integer 0 to n. Evaluates C if i = 0, C1 if i
O
= 1, etc.
ADD[Ol, ... I 01
8 Sum of up to 8 integers 0 ... 08.
1
SUB[Ol,02] 0 -02
1
lFE[Ol,02,Cl ,C2] Evaluates clause C1 if 01 equals 02, else C2.
IFG[01,02,Cl,C2] Evaluates C1 if 01 greater than 02, else C2.
NOT[O 11 Ones coniplernent of 0 1.
OR[01,02, ... , 081 lncliisive 'OR' of up to 8 integers.
xon[o1,02, ... , 081 Exclusive 'OR' of up to 8 integers.
AND[O1,02, ... I 081 'AND' of up to 8 integers.
LSHIFT[Ol,N] 01 lshift N
RSHIFT[Ol ,N] 01 rshift N


OCT in the SLIL'[NAME,OCI'] clrtusc, may bc any exprcssioii which evaluatcs to an integer, e.g.:




7
DO hlicroassembler Manual 20 October 1978



SET" AME,ADD[NOT[X],AND[Y ,Z,3],W]]


Where W, X, Y, and 2 are integers.

If you want do arithmetic on addresses, then the addresses must be converted to integers using the
IP operator, e.g.:

IP[FOO] takes the integer part of the address Fa)
ADD [3,IP[FOO]] is legal
ADD[3;FOO] is illegal

Some restrictions eon doing arithmetic on IM addresses are discusscd later.



9. REPEAT Statements
The assortment of macros and junk in the DOLANG file successfilly conceals Micro's complicated.
macro, neutral, memory, field, and address stuff for ordinary use of the .assembler.

However, one special situation that may require you to understand underlying machinery is
REPEAT statements--in a diagnostic you might want to assemblc a large block of instructions
differing only a little bit from each otlier, and you want to avoid typing the same instruction over
and over.

Instnictions statements are assembled relative to a location counter called JLC. This is originally set
to 0 and is bumped cvery time an instruction is assernhlcd. To do a REPEAT, you must directly
reference ILC as follows: 4
REPEAT[20,1LC[( ... INSTRUCTfON STATEMENT ... )I];
This would assemble the instruction 20 times. If you want to be bumping some field in the
instruction each time, you would proceed as follows:

SET[X,O];
REPEAT[20,1LC[(SET[X,ADD[Xli]] ... instruction statement ... )]]


where the instruction statement would use X sortieplace.

For a complicated REPEAT, you may h a w to know dctails in DOLANG. For this you will have to
delve into it and figurc out how things work.

Multi-instruction REPEAT'S arc also possible. The 'X,C[( ...)I" in the above example -can be used
sevcral tiirics to accomplish this. Howevcr, [he SOO-charackr sizc of llic staterncnl buffcr will limit
the complexity of the KEPEAT body tu only a fcw instructions.




8
DO Microassembler Manual 20 October 1978



10. Parameters
Parameters are special assembly-time data objects that you may define as building blocks from
which CONSTANTS, RM, or I data may be constructed. Two macros define parameters:
M
MP[NAME,OCT]; makes a parameter of NAME with value OCT
SP[NAME,Pl,...,P8]; makes NAME a parameter equal to the sum of P1, ..., P8,
which are parameters or integers.
NSP[NAME,Pl,...,
P8]; makes NAME a parameter equal to the ones complement of
the sum of P I , ..., P8, which are parameters or integers.

The parameter "NAME" is defincd by the integer "NAME!"', so it is ok to use the NAMg again
as an address or constant. However, you cannot use it for more than one of these.

NOTE: The MC and NMC macros discussed in the next sections not only define constants, but
also parameters with the same name (i.e., NAME!) and value.

[The **!*' is a symbol constituent added so that a constant or RM address can have an identical
NAME.



11. Constants
The hardware allows 10-bit constants to be output in either the left or right halves of ALUB with
0's in the other half of the word. In conjunction with arithmetic ALU operations, thc right-half
constant is sign-extended.
4
The assembler pennits literal constants to be written as "122C", "177400C3","177600C3","122000C",
etc. These can be inserted in microinstructions without previous definition. 'The assembler error-
checks the ALU operation in cases where the selected constant requires or prohibits sign-extension.

Negative constants such as "-lC", "-55C", etc., are presently illegal. However, they may be
implemented later, if I can figure out how.

A1tcrnatively, constants may be constructed from parametcrs, integers, or addresses using the
following macros:

...,
MC[NAME]PI, PSI; defines NAME as a constant whose value is the sum of
P1...PS (integers or parameters).
NMC[NAME,P1,...,PSI; defines NAME as the ones complement of the sum.


NOTE: Thc two macros above also define NAME as a parameter. You nzlrst not redcfine a
parameter with thc same name as a constant because the binding of thc constant is to the name of
its associated parameter, not to its value. In othcr words, if you rcdefinc a parameter with the stme
namc as a constant, you will rcdcfinc the constant also.

Occasionally, you may wish to crcate a constant whose value is an aritlimctic cxprcssion or an
expression including an addrcss in KM. Here are several cxmples of ways to do this:




9
DO 12.ficroassembler Manual 20 October 1978



I P[RADD R] C A constant whose value is an RM address
ADD[3,LSHIFT[X,4J]C A constant whose value is a function of the integer X




12. SETTASK Statements
The hardwarc OR'S various bits of the task number into fields of the microinstruction to determine
which RM addresses are referenced. You must tell the assembler what task is going to execute each
section of microcode, so that it can perform the proper error checks and set up the fields of
microinstructions appropriately.

This is done with a clause of the form:

SET TASK[n];

where n is the task number, 0 to 17. If you want to refer to task numbers symbolically, you can
define integers with values equal to the task numbers. For example.:

SET[OISPTASK,S];

Then use SETTASK[DISPTASK] to refer to the task.

SETTASK controls not only the assembly of instructions, but also the allocation of RM addresses to '


100-word sections of RM, as discussed in the next section.

NOTE: The TITLE statement at the beginning of a file does a SETTASK[O].d



13. Assembling Data for RM
RM addresscs are allmatcd by RV statements in one of the following ways:

,...,
RV[name,disp,Pl,P2 P7];
RV[name,,Pl,P2, ...,P7];
RV[name,disp];
RV[narne];
RV[name,disp,value];
RV[name,,value];


The first argument "name" is the namc of the RM addrcss which yoii will subscqucntly use in
instruction statcments.

Tlie sccond argumcnt "disp" is a displacctncnt bctwecn 0 and 77. This spccifics thc low six bits of
the IIM addrcss. 'Thc top two bits are determined by tlic top two bits of thc task numbcr, declared
by the last SITTASK statcmcnt. If' "disp" is omitted, the RM addrcss is allocatcd at the last
location plus 1.




10
DO Iliicroassembler Manual 20 October 1978



The remaining 7 arguments are parameters summed to determine the value loaded into that
location. If all of these are omitted, then the location will be uninitialized,

Avoid assigning useless initial values to variables because this will prevent the "Compare" fbnction
in Midas (which compares the microstore image against what you loaded) from reporting fictitious
errors. In a system microprogram (as opposed to a diagnostic), any Occurrence of a variable with an
initial value is probably a programming error since it requires reloading the microcode to restore the
initial value. Hence, if you have variables with initial values, you probably should store the initial
values elsewhere (in IM, for example), and copy the initial values into the registers during
initialization.

The hardware imposes a number of strange constraints upon the placement of RM addresses. For
example, addresses used as base registers must be less than 4 mod 8, quadruple fetch/store locations
must be 0 mod 4, double fetchlstorc locations must be even. Also, RM is partitioned so that only
locations 0 to 77 are accessible to tasks 0 to 3, 100 to 177 to tasks 4 to 7, 200 to 277 to tasks 10 to
13, and 300 to 377 to tasks 14 to 17. Tasks 1 to 3 in each group of 4 are further limited because
the task number is OR'ed into high address bits in various ways. These constraints will be a source
of many program bugs.

You must be careful to assign a "disp" that satisfies all the uses of each RM address. If you screw
up, the assembler will give you an error message when you subsequently reference the RM location
in an instruction.

Sometimes you may want to use several differcnt names to refer to the same RM location. To do
this, define the first name with RV, as above; then define the synonyms as follows:

RM[F00,IP[FW]];

This defines the address FOOl at the same location as the (previously-defincd) addrds FOO.



14. Assembling Data Items in the Instruction Memory
If you do not want to clutter RM with infrcqucntly referenced constants or variables, and if you are
willing to cope with thc hardware kludges for reading/writing thc instruction mcrnory as data, then
you can store data items in IM.

To assemble a table of data in the instruction mcrnory:

SETIT1 LOC,1001;
DATA[(TABLEl:LH[Pl, ...,Pa] RH[Pl,...,P8], AT[TlLOC]));
DATA[(LH[Pl ,...,P8] RH[P1,...,P8], AT[T1LOC,l])];
...

where TABLE1 is an IM address symbol equal to the location of the first instructioti in the table,
P1, ..., P8 arc parmctcrs, intcgcrs, or addresscs. LH stores thc sum of up to 8 pr'anictcrs in the
left-half of the 1M word and KH, the right-half. "AT" is discussed in Scctioii 2.18.3. Sample
sequences for reading and writing IM are given in Section 5.
DO illicroassernbler hluntial 20 October 1978
I !
.-I
._




15* RM & STK Clauses
-I
-.


The hardware complicates references to RM by providing only six bits of RM address in the
microinstruction. The remaining two address bits come from the task number. The programmer
I1
must declare the task number with SETTASK before referencing any variables or constants.

RM addresses can source ALUA destinations and can be used in ALU expressions: In this case, the
-1
-
RM address has to be enclosed in "()".

RM addresses can be used as destinations for ALU operations and ALU sources (which the
assembler routes through the ALU). For these simply write the rcgister name followed by "*".
*

-1
.--


-1
_-

16* ALU Clauses .. ,



The operations performed by the ALU are given below. In these expressions, the "A" component
' I c .




-I
4




of the ALU expression may be any RM address or one of the other "A" sources. These must be
enclosed in "()". The "13" component may be constaiit, enclosed in "()" or T. *'()'' are optional
around T. :I
17. Memory Referencing Instruction Statements
Instruction Statements that initiate memory refcrences or INPUT have a different form from regular
instructions, as discussed in the hardware manual. Branch and placement clauses are identical to
those in regular instructions, and the F2 clause, if any, is identical to that in a regular instruction.
The rest of the instruction is a single clause in one of the following forms:

PFETCHl[rbase,rdest< ,f2> ]
PFETCti2[rbase,rdest< ,f2 > ]
PFETCH4[rbase,rdest< ,f2 > ]
< >
PSTORE 1 [rbase,rsource ,f2 ]
< >
PSTORE2[rbase,rsource ,f2 ]
< >
PSTORE4[rbase,rsource ,f2 ]
IOFETCH4[rbase,device< ,f2> ]
IOFETCH20[rbase,device< ,f2 ] > *

< >
IOSTORE4[rbase,device ,f2 ]
< >
IOSTORE20[rbase,device ,f2 ]
WRITEMAP[rbase,rsouree ,f2> ]
<
< >
READMAP[rbase,rdest ,f2 ]
INPUT[raddr < ,f2 ]
>

In these clauscs, "rbnsc" is ;in RM addrcss which must bc in the group of 100 acccssiblc to the
ciirrcnt task (scc "SEl"r/\SK")and less than 4 mod 8. The two words of bzlsc address arc takcn
froin the sclccted R M ;iddrcss and that location +4. The asscmbler will give an error if you use an
invalid l



12
D 0 Microassembler h anual
f 20 October 1978



The displacement relative to the base register is taken from T, if you omit the optional f argument
2
(" < > above denotes an optional argument). If you supply the f argument, which must be in
'I 2
integer less than 20, that value is stored in the F2 field of the microinstruction and used instead of
T. See the hardware manual for details on how this works.

PFETCHn will then move n words from the memory to the n-word block of RM addresses
beginning at "rdest". "rdest must be even for PFETCH2 and 0 mod 4 for PFETCH4: it must be in
the group of 100 (task 0 mod 4), 40 (tasks 1 mod 4 and 2 mod 4), or 20 (task 3 mod 4) RM
locations accessible to the task--the assembler will give an error message if "rdest" is illegal.

PSTOREn is like PFETCHn, but moves data from RM to memory.

IOFETCHn moves n words from memory to the selected I 0 device, where the I 0 device must be
specified by an integer. The hardware OR'S the current task number with the 8-bit device in the
instruction, and the assembler will give an error message if the device you code is inaccessible to the
task.

IOSTOREn is like IOFETCHn, but moves data h m the device to memory.

NOTE: The hardware OR'S the current task number into the RM address in the microinstruction
so that a group of 4 tasks will use different RM locations, while executing a single stretch of
microcode. Suppose, for example, that you want tasks 10, 1 , 12, and 13 to share a section of
1
microcode but usc independcnt RM locations. Then do a SElTASK[lO] before that section of
microcode, allocate a block of RM locations in the range 100 to 117 and refer to these locations in
the stretch of microcode: also allocate Parallel blocks of RM locations in the ranges 120 to 137. 140
to 157, and 160 to 177 for use by, task 11, 12, and 13. In this way, the progrc& will do what you
want. If the stretch of microcode also rcfers to constants, allocate these in thc range 160 to 177, so
th3t they will be accessible to all four tasks.



18. Branching
This section defines branch clauscs in instruction statements, dcclarations which affect instniction
placcment, and dispatch clauses.

Micro assemblcs instructions for an imaginary machine identical to D but with additional fields
O
asscmbled for its postproccssor. 'Ihe imaginary machine is characterized by tiill-size 12-bit brmch
addresses in instructions.

A postprocessing program callcd MicroD places instructions and transforms tlzc .DID (micro binary)
output file for the imaginary machine into a .MB file for DO.




13
DO Microassembler Manual 20 October 1978



. 18.1. Branch CIauses
The assembly language defines several constructs of the form:

GOTOEbranch address, branch condition 1, branch condition 21


where both branch conditions are optional.

The branch addresses for these may be either instruction tags or one of the following special
symbols: .-3 .-2.-1..+ 1 .+2 .+3, where "." refers to the current instruction and the&others are
relative to this in-line.

[It is obviously possible to define .-4, .+4, .-5, etc., but my feeling is that it is bad style to jump
hrther than +/-3 without using a tag, If anyone finds this inconvenient, please let me know.]

When complementary branch conditions are used, the assembler simply reverses the order of the
branch tags. Hence, DBLGOTO~AGl9TAG2,cwn C1, corn C2] =
DBLGOTO[TAG2,TAG1,Cl,C2].This is provided as a programming cohvenience.
NOTE: If two branch 'conditions appear in a statement, they must be both regular or both
complementary. When two regular branch conditions are used, the truc path takcs if either is true.
However, when two complementary branch conditions are used, the truc path takes only when both
are true. Don't get confbsed by this.

Below " < > " denote optional args; C1 and C2 either two hardware branch conditions or
complements of two hardware branch conditions:

RETURN To LINK (smashes LINK also).
CORETURN Like RETURN but LINK*. + 1 and 'next instruction in-
line placed at . + 1.
DBLGOTO[TAGl,TAG2,C1< ,C2 > ] To TAG1 if C1 or C2 true, eke to TAG2. Limits
TAG2 to the goto addresses.
DBLCALL[TAGl ,TAG2,C1< ,C2 > 1 = DBLGOTO[TAG1 ,TAG2.C1,C2], forces next
instruction in-line to be at . + 1 mod 100, and limits
TAG2 to call addresses.
CALL[TAG < ,C1< ,C2 > >] = DBLCALL(TAG,.+ 1,C1,C2], complementary BC's
illegal
GOTO[TAG < ,C1< ,C2 > >] = DBLGOTO[TAG,.+ 1,C1,C2]

A conditional CALL is just barely possible. It requires the next instruction in-line to be
simultancously at the truc branch addrcss,xor 1 and at the address of the caller +l. Since the true
branch address must be at a location with three low bits cyual 001, these conditions arc only met
when tho iddrcss of the crtllcr is the location beforc tllc false targct itddrcss. In other words,
complementary I K s arc illcgnl w t CALL, and you cannut code two consecutive microinstructions
ih
each containing a conditional CALL.

It is also impossible to have a CALL in the instruction attcr a conditional GOT0 becausc the return
of the CALL would bc to the true target of thc previous conditional branch.

An unconditional RE'I'UKN branchcs to the address of thc caller +l. There is no placement
constraint on a11 instruction containing a KETUlIN.




24
~ I_.
DO hficroassernbler Manual 20 October 1978



conditional RETURN is not defined by tlie hardware.

If omitted, the branch clause is defaulted to GOTO[.+l].



18.2. Dispatch Clauses
The assembly language defines the following dispatch clauses (or slow branches):

DISPATCH[RADDR,POS,SIZE] Dispatch on 1 to 8 bits from RADDR
BBFA[RADDR]
NEXTlNSTtRADDR]


An example using a dispatch clause is given in. the next section.



18.3. Placement Declarations
An instruction containing the clause "AT[N]" will be forced by the assembler to appear at absolute
location N in the microstore. This will be necessary for instructions in dispatch tables.

"AT[Nl,N2]" in an instruction is cquivalent to AT[ADD[Nl,N2]]. For example, an 8-way
DISPATCH might be written as:

DISPATCH[RTEMP,0,3];
..., GOTO[SWITCH];

SET[SWLOCI32O];
SWITCH: ..., AT[SWLOC]; 'B[ 15:171= 0
..., AT[SWLOC,l]; +B[15:17]= 1
...
..., AT[SWLOC,7]; 'B[15:17] =7

where the three instructions in tlie dispatch necd not be consccutive in the assembly source.

NOTE: Because microinstruction addresses are unknown during asscmbly, it is illcgal to create
paramctcrs, constants, or R-memory data-rcfcrring in any way to instruction locations. To do this,
you must manually locatc the affcctcd instructions with "A?'" statcmcnts and do arithmctic on
integers with the s;mc valucs as the instruction locations.

Global entries arc declared by a "GLOBAL" clause in a statcment, e.g.:

DONEXT: RETURN, T+377CI GLOBAL;


GLOBAl, declarations cause placetiicnt at one of thc 20 global call locations in thc microstore.
DO Microassembler Manual 20 October 1978 - - '1




It would probably be nicer for the assembler to have some way of positioning an instruction at a
boundary of 4, 10, 20, etc., without forcing the absolute location to be completely specified.
However, I decided this was:harder to implement and it will not be provided-you are stuck with
"AT" for all dispatch tables,




16
MICRO
MACHINE-INDEPENDENT
MICROASSEMBLER

29 August 1978




Edward Fiala
Peter Deutsch
Butler Lampson

Xerox Palo Alto Research Center
3333 Coyote Hill Road
Palo Alto, California 94304


This manual describes a machine-indepcndent microassetribly language originally developed for the M a c 1
computer and since uscd for the Maxc2. Ilorado, and DO computers as well as for several smaller projects.

This manual is the property of Xerox Corporation and is to bc uscd solcly for evaluative purposes. No part
thereof may be reproduced. stored in a rctrieval system transmited, disseminatcd, or disclosed to others in any
form or by any mcnns without prior written permissioii of Xerox.
Micro: Machine-lndependen t hiicroassem bler 29 August 1978




1. Introduction
This document describes MICRO,originally implemented in 1971 for NOVA in Algol to assemble
microprograms for the M a c 1 microprocessor. It has since been reimplemented for Alto in Bcpl
and is now used to assemble microprograms for Maxcl, Maxc2, Dorado, and DO. Its output format
is compatible with the MIDAS loaderldebugger, for which there are versions on each of these four
machines.

Micro is a rather unspecialized one-pass assembler. It does not know anything specific about the
target machine, but instead has a general facility for defining fields and memories, a standard string-
oriented macro capability, and a rather unusual parsing algorithm which allows setting fields in
memories in a natural way by defining suitable macros and neutrals with properly chosen names.

This document will be of interest primarily to someone who is going to define a new assembly
language for some machine. There are a number of complications inside Micro that this person
must be! aware of when defining the language. However, once the language has been appropriately
defined, the interface seen by someone writing programs for a target machine is natural and simple.

In other words, if you were going to write microprograms for Dorado or DO, for example, you
would need to read "The Dorado Microassembler" or "The D Microassembler", which define
O
languages for those machines, but would probably not require this document.


2. Assembly Procedures
To assemble microprograms on your Alto, you must obtain [Mac] < Alto > Micro.run or
[IVY]Micro.run. In addition, you will need to gct the dcfinition filc(s) for the particular
microlanguage that you will be using (see other relevant documentation).

Micro flushes Bravo trailers, so you can use Bravo formatting in the preparation of microprograms.
Howcver, MCross, a M a c program that produces cross-reference listings of Micro programs, does
not ignore Bravo trailers, so you maj' not use ady Bravo formatting fcatures if you are going to use
MCross. In addition, error mcssagcs produccd during asscmbly have linc numbers that will be
morc difficult to correlate with source statements if automatic Bravo line breaks occur in thc source
tcxt rather than explicit carriage returns,

Wc recommend use of GACHh8 (i.e., a relatively small fixcd pitch font) for printing hardcopy
microprogram listings, and thc use of GACHA 10.AL for editting microprograins with Bravo. Dravo
tab stops should bc set at precisely 8 character interals for idcntical tabulation in Bravo and MCross.

'I'hc two relevant lines in USER.CM for Bravo are:

F0NT:O CACIIA 8 GACIIA 10
TABS: Standard tab width = 1795

You will probably want to dclcte the other Font lincs for nravo in USER.CM.

Supposc that you havc preparcd a languagc dcfinition file LANG.MC and a numbcr of sourcc files
for asscmbly by Micro. TIicii n microassembly is xcomplishcd by tlic following dialog with the

r7
kIicro: Muchine-Indeperiderit Microassembler 29 August 1978



Alto Executive:

MICROIL LANG SRCO SRCl ... SRCn

This causes the source files "LANG.MC", "SRCO.MC", ... , "SRCn.MC" to be assembled. The
binary output and symbol table at the end of assembly are written onto "SRCn.MB" and
"SRCn.ST", the error messages onto "SRCn.ER", and an assembly listing onto "SRCn.LS".

In other words, Micro assembles a sequence of source files with default extension ",MC" and
outputs four files whose extensions are ".MB", ".ER", *'.LS", '*.ST". The default name for
and
these is the name of the last source fire assembled. Direct output to particular files as follows:

MICRO SYS/L/B LANG SRCO SRCl ... SRCN

This would cause listing output to be put on "SYS.LS'*and symbol table and binary output onto
"SYS.ST" and **SYS.MB'.
. - . .
A s m a y of the local and global nags for Micro is as follows:
umr '
- . . L




Global: /L produces an expanded listing of the output
/N suppress binary output
/O suppress symbol table output
/U convert text in all source files t upper case
o

Local: /R recover from symbol table file.
/L put expanded listing on named file
/B puts binary output and symbol table output on named file with extensions .MB and .ST,
respectively. Default error listing to named file.
/E put error listing on named file
/S put symbol table on named file
\ /U convert text in named file (and any file which it INSERT'S) to upper case

Local flags override global ones.
INSERT[file];

statements may be put into source files so you don't have to type as many source names on the
command line. This is exactly equivalcnt to the text of fi1e.m. INSERT'S may be ncstcd to a
reasonable depth. Howevcr, although INSERT saves typing it is slower than putting the file names
on the command line because Micro uses a fast file-lookup routine to get handles on every file
named in the command linc in about 1 second; each INSERT adds a11 additional 1 sccond for file
name lookup.

Another shortcut is to define a command file MI containing "Micro/O/U LANG" or whatever and
then type @MI@? SRCO ... SRCN", which avoids some typing.

The SE'I'MlIEXT[.ext] builtin allows the binary output filc cxtension to bc changcd from .MB to
somcthing clsc. 'rhis dcclaration has to be asscmblcd bcforc dcfining any inemorics (clsc the output
file will havc alrcady been opened with cxtension .MB). The Dorado and D microassemblers use
O
this to change the extension to .DIB, as expected by the postprocessor, MicroD.



18
Micro: Machine-Independeat Microassembler 29 August 1978



Micro creates a temporary file Micro.fixups and deletes it at the end of assembly. If you abort
assembly with shift-swat, you may delete it yourself.

Micro's binary output is generated in one pass and consists of memory definitions, store directives
to memories, forward and external reference fixup directives, and new or changed address symbols
for each memory. The block types written on the output file are given in =Appendix 3.

Micro assembles declarations at a rate of about 60 statements/second and, wt typical ih
microlanguages, assembles microinstructions at about 7 statements/second. On very large assemblies
this rate slows slightly as the symbol table grows larger. The assembly time for the M a c system
microcode is about 7 minutes (-2000 72-bit microinstructions, -500 36-bit words in other
-
memories, -500 definitions, and 1400 addresses).

Comments are flushed very quickly by the prescan, so do not worry about a profixion of comments
slowing assembly.

Presently, the: Micro-Midas system has no provision for relocating independerotly assembled source
progrlims. However, the Micro symbol table is dumped onto a file at the end of the assembly.
Later, assembly can be continued at that point onto another binary output file, thereby reducing
assembly time. For example, you can build a LANG.ST file as follows:

MICRO LANG

Then do all hrther assemblies as follows:

MICRO/OU LANG/R SYS/B SRCO ... SRCN

This saves a little assembly time but still does not allow several people to indcpendently maintain
sources used in a common system.

To avoid reassembling unchanged files, one would have to partition his program into separate
asscmblies, each of which used absolutc location-counters for the various memorics. This would be
difficult, probably not as good as reassembling everything. However, if this were done, Midas could
link external refercnccs between the different modules at load time.

The MicroD program, used to post-process Micro assemblies for Dorado and DO, has limited
provisions for rclocation. Programmers using the Ilorado or D microlanguages should read the
O
relevant documcntation.
Micro: Machine-Independent Microassembler 29 August 1978



3. Error Messages
During assembly, any error messages are output both to the terminal and to the error file. If an
assembly listing is being printed, the error messages are also printed there.

As Micro chums through the source files it prints the name of each on the error file (and terminal),
and when INSERT[file] statements appear it outputs "* FILE file ..." and "* RETURN to file"
messages. These will pinpoint any error message to a particular source file.

Micro error messages are in one of two forms, like the following:

statement
218...error message

statement
TAG+39...error message

The first example indicates an error in a statement beginning on the 218th line of the source @e.
This form is used for errors that precede the first label in the source file. The sFond form is used
afterwards, indicating an error on the 39th line after the label "TAG", Micro also prints the source
statement causing the error before printing the error message.

Note that the line count measures carnage returns in the source, so if you are using Bravo
formatting in the source files, you may have trouble distinguishing carriage returns from line breaks
inserted by Bravo's hardcopy command.

ER is the builtin by which a Micro program outputs messages to the error file (and to the terminal),

ER[message,stopcode,value]

Blanks are squeezed out of the message by the prescan so "J' signs or other printing characters
should be uscd instead.

S topcode equal 0 continues assembly; non-zero aborts assembly (nulstring in the stopcode defaults
to 0).

ER first prints the message (a literal string) on the error file: