****************************************************************************
*								           *
*	MASM - Merlin Assembler					           *
*								           *
*	Proprietary and confidential to VM Labs, Inc.		           *
*								           *
*	June 4, 1995						           *
*	Version 1.2							   *
****************************************************************************

I. Introduction

 MASM is an assembler for the Merlin processor. Merlin's 
processor elements are each fully independent and therefore its 
instructions are rather complex. Because of that MASM has to break with
the syntax of traditional assemblers where each line contained one
specific instructions. 


II. Merlin Function Units

 The Merlin processor has six distinct functions units, each operating 
in parallel. The following is a list of these units:

	ALU = Arithmetic Logic Unit
	MDU = Multiply Unit
	MUA = Memory Unit A
	MUB = Memory Unit B
	RU  = Register unit
	PBU = Program branch unit


III. Instruction Syntax

 MASM allows for two ways of describing a complex Merlin instruction.
The first one is called the one-line description:

 ALU instr ! MDU instr ! MUA instr ! MUB instr ! RU instr ! PBU instr

 The unit instructions do not have to appear in the above order. The
assembler is cabaple of putting the FUIs (Function Unit Instructions)
into the right order when forming the Merlin instruction.

 The disadvante of the one-line description is that it does not leave
much room for comments. Because of that, a Merlin instruction can
also be described in a multi-line description:
	
	{ ALU instr,
	  MDU instr,
	  MUA instr,
	  MUB instr,
	  RU  instr,
	  PBU instr
	}

 Again, the programmer does not have to take care of the order of the
FUIs.


IV. Source Line Format

IV.1 Statements

 The following describes the general form of an assembler statement:

label:	ALU fui ! MDU fui ! MUA fui ! MUB fui ! RU fui ! PBU fui ; comment

 The minimum of one fui is necessary to form an instruction. All others
are optional. The other form of describing a statement is:

label:	{ ALU fui	; comment
	  MDU fui	; comment
	  MUA fui	; comment
	  MUB fui	; comment
	  RU  fui	; comment
	  PBU fui	; comment
	}

 The label, if it appears, must be terminated with a single or a 
double colon. A double colon will declare the label as global.


IV.2 Comments

 There are two kinds of indicating a comment field

	; comment until end of line
	/* comment in between the stars */

 A semicolon anywhere on a line begins a comment field which end at the
end of the line. 

 A slash followed by a star '/*' begins a comment section which then ends
with a star followed by a slash '*/'. This type of comment is allowed
anywhere on a line and can be used to put comments in-between FUIs on
a single-line description.


IV.3 Instruction Syntax

IV.3.1 ALU Instructions

IV.3.1.1 Overview

 Most ALU instructions use two operands and write the result into a
register. They also allow for a right shift on the first operand. Therefore
a general instruction looks like this:

	OPERATION [src_a [>> [~]shft_a]] [, src_b] [, dst]

	src_a		Source A, register R0-R11.
	src_b		Source B, register R0-R11.
	dst		Destination, register R0-R11.
	>> 		Introduces an optional right shift of source a.
	~		Indicates that instead of a right shift a right
			rotate will be performed. 
	shft_a		Right shift amount for source a. The amount has
			to be a constant


 "Src_a" specifies the register for source operand 1, "src_b" is the 
2nd source operand and "dst" is the destination register where the result of
the operation will be stored. "Shft_a" is the amount for an additional right 
shift of source operand 1. If a tilda ('~') preceeds the shift amount, the 
amount is rotated instead of shifted.

Source registers are: 	R0 - R11
Destinion register is:	R0 - R11
Shift amount:		Constatabt value speciefied in the instruction.



	Example:
		add r1 >> #2, r2, r3

		Use the contents of register R1, shift it right by 2 and add
		it to the contents of register R2. Store the result in R3.	


	Arithmetic Mode

		nopa
		- No operation (ALU).

		movei <constant>, a
		- moves immediately a constant to register 'a'.
	

		or	a [>> x], b, c
		- (Bitwise) Or registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		dec	a
		- Decrement register 'a',

		add	a [>> x], b, c
		- Add registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		sub	a [>> x], b, c
		- Subtract register 'a' from 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.


	Boolean Mode
	
		not	a
		- Perform a logical not on register 'a'.

		nor	a [>> x], b, c
		- (Logical) Nor registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		zero
		- Set the conditional codes to the equivalent of writing
		  back a result of zero.

		nand	a [>> x], b, c
		- (Logical) Nand registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		xor	a [>> x], b, c
		- (Logical) Xor registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		xnor	a [>> x], b, c
		- (Logical) Xnor registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		setto	b
		- ????
	
		and	a [>> x], b, c
		- (Logical) And registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		one
		- Set the conditional codes to the equivalent of writing
		  back a result of zero.

		or	a [>> x], b, c
		- (Logical) Or registers 'a' and 'b', result is stored in 'c'.
		  'x' is an optional right shift amount.

		setto	a
		- ????

		

		
IV.3.2 MDU Instructions

 Like the ALU instructions, the MDU instructions contain two source registers
and one destination register. In addition to R0-R11, the accumulator (AC) can
be specified as the destination. The result can either be stored in or added
to the accumulator.

	mulu	a, b, c
	- Unsigned multiplication of source 'a' and 'b'. Result is stored
	  in register 'c'.

	muls	a, b, c
	- Signed multiplication of source 'a' and 'b'. Result is stored
	  in register 'c'.

	mulu	a, b, AC
	- Unsigned multiplication of source 'a' and 'b'. Result is stored
	  in the accumulator.

	muls	a, b, AC
	- Signed multiplication of source 'a' and 'b'. Result is stored
	  in the accumulator.

	mulu	a, b, +AC
	- Unsigned multiplication of source 'a' and 'b'. Result is added
	  to the accumulator.

	muls	a, b, +AC
	- Signed multiplication of source 'a' and 'b'. Result is added
	  to the accumulator.


	Example:
		mulu r0, r1, r2

		Unsigned multiplication of r0 and r1. Result is stored in r2.


IV.3.3 MUA, MUB Instructions

 Memory unit instructions are used to load data into and store data from 
registers. Two memory units, 'A' and 'B', exists and are identified in the
memory unit instructions by the appended characters 'a' and 'b'.

 UNIT A

	loada	(<ea>), reg
	- Load a 32 bit long word from the effective address into the 
	  specified register.

	storea	reg, (<ea>)
	- Store a 32 bit long word from the specified register into the
	  effective address.

	loadla	<ea>, reg
	- Load a 128 bit line from the effective address into the 
	  specified register.
	storela	reg, (<ea>)
	- Store a 128 bit line from the specified register into the
	  effective address.

 UNIT B

	loadb	(<ea>), reg
	storeb	reg, (<ea>)
	loadlb	<ea>, reg
	storelb	reg, (<ea>)

 Effective addresses (<ea>) are:

		base_reg
		- Effective address is specified in register.

		base_reg + x[+=m]
		- Effective address is the sum of the specified register and
		  the X register. An optional register 'm' can be specified
		  for a postincrement of register X with 'm'.

		base_reg + y[+=m]
 		- Effective address is the sum of the specified register and
		  the Y register. An optional register 'm' can be specified
		  for a postincrement of register Y with 'm'.

		base_reg + z[+=<1,4>]
		- Effective address is the sum of the specified register and
		  the Z register. An optional value of '1' or '4' can be 
		  specified for a postincrement of register Z by '1' or '4'.

		base_reg + c[-=1]
		- Effective address is the sum of the specified register and
		  the C register. An optional value of '1' can be 
		  specified for a postdecrement of register C by '1'.

	Example:
		loada	(r1 + x+=r2), r5

		Using memory unit a, a long word gets loaded into r5. The 
		effective load address of the sum of registers r1 and x. After
		the load, register x gets incremented by the value of r2.


IV.3.4 PBU Instructions


	bra cc, <relative offset>
		- The <realtive offset> (-15/+15) gets added to the PC if the
		  condition code <cc> is true.

	jump cc, <absolute address>
		- A jump to the absolute address is taken if the condition 
		  code is true.


IV.4 Equates

 A statement may also take one of these special forms:

	symbol equ    expression
	symbol =      expression
	symbol ==     expression
	symbol set    expression
	symbol regset expression
 
 The first two once are identical: they equate a symbol to the value of
an expression. The third form make the symbol global. The fourth 
form treats the symbol like a variable so that in can be set a number
of times. The last one sets a symbol to a register.

Examples:
	n	equ 	3
	DPA	regset	r0


IV.5 Symbols and Scope

 Symbols may start with any letter (A-Z, a-z) or an underscore. Each 
remaining character may be a letter, a digit, an underscore or a
dollar sign. The first 32 characters are significant.

Keywords

 The  following names are keywords and may not be used as symbols:

	equ, set, regset
	ac, x, y, z, c, pc, cc
	r0, r1, r2, r3, r4, r5, r6, r7, r8, r9, r10, r11

 Please note that the keywords are not case sensitive.


IV.6 Constants

 A number may be decimal, binary, octal, hexadecimal or concatenated
ASCII. The default is decimal. Hexadecimal number are specified with 
a leading dollar sign. Binary numbers are recognized by a leading
percent sign. Octal number are specified by a leading at-sign. ASCII 
strings are  enclosed in quotes.

Examples:
	5431	decimal
	$12a0	hexadecimal
	@423	octal
	%1101	bibary
	"Hallo"	ASCII

	
IV.7 Expressions

 Expression values are computed with 32-bit arithmetic. Expressions are
evaluated from left to right, with no regard for operator precedence.

Operators

	Binary Operators
	
		+	Add
		- 	Subtract
		*	Multiply	
		/	Divide
		%	Modulo
		& 	Bitwise And
		|	Bitwise Or
		^	Bitwise Xor
		<<	Logical Shift Left
		>>	Logical	Shift Right
		
	Unary Operators
	
		-	Unary Minus
		+	Unary Plus

 Parentheses may be used to modify the order of expression evaluation.


IV.8 Addressing Modes



IV.9 Assembler Directives

 All assembler directives are preceded by a period.


.ALIGN	- Align code or data to a specific address boundary

	.Align	AlignmentType

 Where AlignmentType is one of:
	- Byte (8 Bit)
	- Word (16 Bit)
	- Long (32 Bit)
	- Phrase (64 Bit)
	- Line (128 Bit)


.DC	- Define constant data

	.DC.<T>	Data[, Data]

 Where <T> defines the data type:
	
	- B	Byte (8 bit)
	- W	Word (16 bit)
	- L	Long (32 Bit)
	- P	Phrase (64 Bit)
	- E	Line (128 Bit)

.DS	- Define storage for data items

	.DS.<T>	N

 Where <T> defines the data type:
	
	- B	Byte (8 bit)
	- W	Word (16 bit)
	- L	Long (32 Bit)
	- P	Phrase (64 Bit)
	- E 	Line (128 Bit)

.ELSE	- Alternative action or .IF directive

.END	- End of assembly

.ENDIF	- End of IF...ELSE directive

.EQU	- Assigns a permanent value to a symbol

	SymbolName	EQU	IntegerExpression


.EXTERN	- Define a symbol as external

	.EXTERN	Symbol


.GLOBL	- Define a symbol as global

	.GLOBL	Symbol


.IF 	- Begin conditional assembly

	.IF <expr> [<RelOp> <expr>]


.INCLUDE - Include another file

	.INCLUDE	"<Filename>"


.ORG	- Begins assembly in the absolute section

	.ORG	AddressValue


.REGSET - Define a name for a register

	RegName	.REGSET	Register

 Defines a new alias name for a register.


.SET	- Assign a non-permanent value to a label

	SymbolName	.SET	Expression

 Defines a symbolic name for a value that can be changed later.




