.TH rspasm 1P local "Silicon Graphics, Inc."
.SH NAME
rspasm \- Ultra 64 signal processor (RSP) assembler.
.SH SYNOPSIS
\f3rspasm\f1 [options] srcfile
.br
.SH DESCRIPTION
.I rspasm\^
is a two-pass assembler for the Ultra 64's Reality Signal Processor (RSP).
It translates RSP source code into an RSP executable which can be
executed on the RSP simulator (\f2rsp\f1), or the RCP hardware.
.PP
The assembly language for the RSP does not conform to the 
\f2MIPS Assembly Language Programming Guide\f1, although in many
places it is similar. The language supports labels, data symbols,
named registers, and simple expressions.
.PP
By default, the RSP assembler input passes through '/usr/bin/cc -E'
(the MIPS ANSI equivalent of the traditional /usr/lib/cpp) so 
C-preprocessor macros such as 
.B #define 
and 
.B #include 
are supported,
as well as C comment syntax 
.B /**/.
.PP
If requested, the output of the C pre-processor is passed through the
m4 macro pre-processor [see 
\f2m4(1)\f1
], before assembly.
.PP
Similar to other MIPS compilers and assemblers, \f2rspasm\f1 defines
the name 
.B _LANGUAGE_ASSEMBLY 
which you can use around any code that
might be shared between C and assembly, such as header files.
.PP
There is no linker; a single text segment is built with each
compilation. There can be only one base address for the text segment.
.PP
A single initialized data segment is permitted, and pseudo-opcodes
(directives) are provided to control where it is located and what
it contains.
.PP
Command line options are:
.RS 5
.TP 12
.B \-D<name>
Define symbol <name> to the C pre-processor.
.TP
.B \-E
Run only the pre-processor(s), don't assemble.
.TP
.B \-I<dir>
Add a directory to the include file search path.
.TP
.B \-S <file>
Object file to search for external symbols.
.TP
.B \-c
Do not run the source through /usr/bin/cc -E (MIPS ANSI C pre-processor)
.TP
.B \-d
Turn on yacc debugging. May be useful for advanced debugging.
.TP
.B \-h
List command line options.
.TP
.B \-l
Do not generate a listing file.
.TP
.B \-m
Run the source through the m4 macro pre-processor after 
\f2/usr/bin/cc -E,\f1
before assembly.
.TP
.B \-o <file>
Name of output file (default is a.out).
.PP
\f2srcfile\f1 is the name of the RSP assembler source code file.
.PP
.SS "\f2RSP Instruction Set\f1"
The RSP instruction set is essentially a 32-bit subset of the
R4000 instruction set, with some extensions. Instructions which 
are not implemented include: any 64-bit instruction, mulitplies, 
divides, branch likely, and most system control opcodes.
.PP
The RSP vector unit (VU) is implemented as a MIPS co-processor (COP2),
with the machine language conforming to the MIPS co-processor
definition. The RSP assembler uses a mnemonic syntax for each
VU instruction.
.PP
.SS "\f2RSP Assembler Directives\f1"
The RSP assembler syntax includes pseudo-opcodes which
direct compilation. Briefly, they are:
.RS 5
.TP 12
.B .align <iexpression>
The current location of the text or data section is aligned to the
next multiple byte boundary corresponding to the evaluated
.B <iexpression>;
possibly adding padding.
.TP
.B .bound <iexpression>
This directive performs a check, printing out an error message and
aborting compilation if the current location within the text or
data section is
.B not
aligned to the next multiple byte boundary corresponding to the
evaluated
.B <iexpression>.
.TP
.B .byte <iexpression>
Initialize the next byte of the data segment to the value <data>.
.TP
.B .data [<expression>]
Switch to the data section. All data initialization directives
must be contained in the data section.

If the optional
.B <expression>
is present, it is evaluated and used as the base address to continue
packing the data section. Only the least significant 12 bits of
the base addres is used, since DMEM is only 4K bytes.

Multiple base addresses are permitted, any "holes" between initialized
data will remain un-initialized. The assembler keeps track of the
maximum address initialized, and all data up to that point (including
any holes) will be output.
.TP
.B .dmax <iexpression>
This directive performs a check, printing out an error message and
aborting compilation if the current location within the text or
data section exceeds the value corresponding to the evaluated
.B <iexpression>.
.TP
.B .end <identifier> [, <expression>]
End a procedure. The assembler outputs debugging information for the
debugger, including the beginning and ending locations of procedures.
.TP
.B .ent <identifier> [, <expression>]
Begin a procedure. The assembler outputs debugging information for the
debugger, including the beginning and ending locations of procedures.
.TP
.B .half <identifer> | <iexpression>
Initialize the next half-word (16 bits) of the data
segment to the value <data>. Aligns to 16-bit boundary.
.TP
.B .name, <identifier>, <register>
Associate the name 
.B <identifier> 
with the register 
.B <register>.
.TP
.B .print <string> [, <expression>][, <expression>] ...
The quoted
.B <string>
constant is printed to 
.B stderr
during program assembly.

The string constant may contain C-like numeric printf conversions
(%d, %x, etc.) and the 
.B <expression>'s
will be evaluated and printed to
.B stderr.

A maximum of four
<expressions>'s
are permitted per 
.B .print
directive.
.TP
.B .space <expression>
If we are in the data section,
.B <expression>
number of bytes are allocated and filled with zeros. The new
current location of the data section will be equal to the
previous location, plus
.B <expression>
bytes.

If we are in the text section,
.B <expression >> 2
number of instructions are padded and filled with
.B nop's
and the new program counter for assembly will be equal to the
old program counter, plus
.B <expression>
bytes.
.TP
.B .symbol <identifier>, <expression>
The 
.B <identifier>
is entered into the symbol table with the value of
.B <expression>.
.TP
.B .text [<expression>]
Switch to the text section. All program instructions must be contained
in the text section.

If the optional
.B <expression>
is present, it is evaluated and used as the base address for
assembling the program. Only the least significant 12 bits of the
base address is used, since IMEM is only 4K bytes.

Only one 
.B .text
directive with a base address may be present, otherwise unpredictable
program assembly will result.
.TP
.B .unname <identifier>
Removes
.B <identifier> 
from the symbol table.
.TP
.B .word <identifier> | <iexpression>
Initialize the next word (32-bits) to the value of the
.B <identifer>
or
.B <iexpression>.

.SS "\f2Assembler Output\f1"
The
.B rspasm
assembler outputs several specially-formatted files. The
root filename for these files can be specified with the
.B -o
flag.
.RS 5
.TP 12
.B <rootname>
is the binary executable code (text section). This file
can be loaded into the RSP simulator and executed.
.TP
.B <rootname>.dat
is the binary data section. This file
is usually loaded into DMEM.
.TP
.B <rootname>.lst
is a text program listing.
.TP
.B <rootname>.sym
is a "symbol file" used by the RSP simulator to perform source
level debugging
.TP
.B <rootname>.dbg
is a "symbol file" used by the 
.I rsp2elf
utility in order to build an ELF object that can be used
with 
.I makerom
and the 
.I gvd
debugger.

.SS "\f2BNF Specification of the RSP Assembly Language\f1"

This section presents a formal specification of the RSP assembly 
language using a Backus-Naur Form (BNF).

.nf
\f3
<program> ::= <instruction> | <program> <instruction>


<instruction> ::= <directive> |
	<label> <directive> |
	<label> <label> <directive> |
	<scalarInstruction> |
	<label> <scalarInstruction> |
	<vectorInstruction> |
	<label> <vectorInstruction>


<directive> ::= .align <iexpression> |
	.bound <iexpression> |
	.byte <iexpression> |
	.data |
	.data <iexpression>
	.dmax <iexpression>
	.end |
	.end <identifier> |
	.ent <identifier> |
	.ent <identifier> , <integer> |
	.half <identifier> |
	.half <iexpression> |
	.name <identifier> , <scalarRegister> |
	.name <identifier> , <vectorRegister> |
	.name <identifier> , <controlRegister> |
	.print <qstring> |
	.print <qstring> , <expression> |
	.print <qstring> , <expression> , <expression> |
	.print <qstring> , <expression> , <expression> , 
		<expression> |
	.print <qstring> , <expression> , <expression> , 
		<expression> , <expresion> |
	.space <expression> |
	.symbol <identifier> , <expression> |
	.text |
	.text <expression> |
	.unname <identifier> |
	.word <identifier> |
	.word <iexpression>


<scalarInstruction> ::= <regOp> <scalarRegister> |
	<regRegOp> <scalarRegister> |
	<regRegOp> <scalarRegister> , <scalarRegister> |
	<regRegOp> <scalarRegister> , <controlRegister> |
	<regRegRegOp> <scalarRegister> , <scalarRegister> , 
		<scalarRegister> |
	<regImmOp> <scalarRegister> , <expression> |
	<regRegImmOp> <scalarRegister> , <expression> |
	<regRegImmOp> <scalarRegister> , <scalarRegister> , 
		<expression> |
	<regOffsetOp> <scalarRegister> , <expression> |
	<regOffsetOp> <expression> |
	<regRegOffsetOp> <scalarRegister> , <scalarRegister> , 
		<expression> |
	<regOffsetBaseOp> <scalarRegister> , <expression> ( 
		<scalarRegister> ) |
	<regRegShiftOp> <scalarRegister> , <scalarRegister> , 
		<expression> |
	<sRegRegRegOp> <scalarRegister> , <scalarRegister> , 
		<scalarRegister> |
	<targetOp> <expression> |
	<vRegsRegOp> <vectorRegister> [ <element> ] , 
		<expression> ( <scalarRegister> ) |
	<sRegvRegOp> <scalarRegister> , <vectorRegister> |
	<sRegvRegOp> <scalarRegister> , <vectorRegister> [ <element> ] |
	<noOperandOp>


<vectorInstruction> ::= <veRegvRegvRegOp> <vectorRegister> , 
		<vectorRegister> , <vectorRegister> |
	<veRegvRegvRegOp> <vectorRegister> , 
		<vectorRegister> , <vectorRegister> [ <element> ] |
	<vdRegvRegOp> <vectorRegister> [ <element> ] , 
		<vectorRegister> [ <element> ] 


<regOp> ::= jr


<regRegRegOp> ::= add | addu | and | nor | or | slt | sltu 
		| sub | subu | xor


<regImmOp> ::= lui


<regRegImmOp> ::= addi | addiu | andi | ori | slti | sltiu | xori


<regOffsetOp> ::= bgez | bgezal | bgtz | blez | bltz | bltzal


<regRegOffsetOp> ::= beq | bne


<regOffsetBaseOp> ::= lb | lbu | lw | lh | lhu | sb | sh | sw


<regRegShiftOp> ::= sll | sra | srl


<sregRegRegOp> ::= sllv | srav | srlv


<targetOp> ::= j | jal


<vRegsRegOp> ::= lbv | lsv | llv | ldv | lqv | lrv | lpv | 
		luv | lhv | lfv | ltv | sbv | ssv | slv | sdv | 
		sqv | srv | spv | suv | shv | sfv | swv | stv


<sRegvRegOp> ::= mfc2 | cfc2 | mtc2 | ctc2


<noOperandOp> ::= nop | vnop | break


<veRegvRegvRegOp> ::= vmulf | vmacf | vmulu | vmacu | 
		vrndp | vrndn | vmulq | vmacq | vmudh | vmadh | vmudm | 
		vmadm | vmudn | vmadn | vmudl | vmadl | vadd | vsub | 
		vabs | vaddc | vsubc | vsar | vand | vnand | vor | vnor | 
		vxor | vnxor | vlt | veq | vne | vge | vcl | vch | 
		vcr | vmrg


<vdRegvRegOp> ::= vmov | vrcp | vrsq | vrcph | vrsqh | vrcpl | vrsql


<expression> ::= ( <expression> ) |
	<integer> |
	<identifier> |
	~ <expression> |
	<expression> & <expression> |
	<expression> | <expression> |
	<expression> ^ <expression> |
	<expression> << <expression> |
	<expression> >> <expression> |
	<expression> * <expression> |
	<expression> / <expression> |
	<expression> % <expression> |
	<expression> + <expression> |
	<expression> - <expression> |
	- <expression> |
	+ <expression>


<iexpression> ::= ( <iexpression> ) |
	<integer> |
	~ <iexpression> |
	<iexpression> & <iexpression> |
	<iexpression> | <iexpression> |
	<iexpression> ^ <iexpression> |
	<iexpression> << <iexpression> |
	<iexpression> >> <iexpression> |
	<iexpression> * <iexpression> |
	<iexpression> / <iexpression> |
	<iexpression> % <iexpression> |
	<iexpression> + <iexpression> |
	<iexpression> - <iexpression> |
	- <iexpression> |
	+ <iexpression>


<scalarRegister> ::= <identifier> |$<integer> | $sp | $s8 | $at | $ra


<vectorRegister> ::= <identifier> | $v<integer> | $vco | $vcc | $vce


<controlRegister> ::= <identifier> | $c<integer>


<element> ::= <iexpression> | <iexpression>h | <iexpression>q


<identifier> ::= <alpha> <alphanumeric>*


<alphanumeric> ::= {<alpha> | <digit> | _}*


<qstring> ::= " {<ASCII text> | <whitespace> | 
		<C print specifier>}* "


<alpha> ::= a | b | c | d | e | f | g | h | i | j | k | l | 
		m | n | o | p | r | s | t | u | v | w | x | y | z |
		A | B | C | D | E | F | G | H | I | J | K | L | M |
		N | O | P | Q | R | S | T | U | V | W | X | Y | Z


<integer> ::= <digit>* | 0x<hexdigit>* | 0X<hexdigit>* |
		0<octdigit>*


<digit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 


<hexdigit> ::= <digit> | a | b | c | d | e | f | 
		A | B | C | D | E | F


<octdigit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7

\fP
.fi


.SH NOTE
The RSP Assembly Language is a proprietary interface.

.SH SEE ALSO
.IR rsp (1P), 
.IR m4(1), 
.IR "Nintedo Ultra64 RSP Programmer's Guide"