Assembly language

This page describes the assembly language spimbot assembles. Simulator describes the machine a program runs on.

Each line holds zero or more statements separated by ;. A # outside a string or character literal starts a comment that runs to the end of the line. A statement is any number of labels followed by at most one directive, instruction or constant definition.

# Prints "hello" and exits.
	.data
hello:	.asciiz	"hello\n"

	.text
main:
	li	$v0, 4		# print_string
	la	$a0, hello
	syscall
	jr	$ra

Mnemonics are case-insensitive. Directive names, labels, constants and register names are case-sensitive, and register names are lowercase.

A name starts with a letter, _ or . and continues with letters, digits, _ and .. name: defines a label at the address of the next item.

Operands are separated by commas, and the commas are required.

Integers are decimal (42, and 010 is ten) or hexadecimal (0x2a). Write negative numbers with a unary minus. A character literal such as '*' is one byte. A floating-point literal has a point with digits on both sides, an exponent, or both, such as 1.5, 2e3 and 6.02e-23. Only .float, .double, li.s and li.d accept one.

Strings are double-quoted and stay on one line. Strings and character literals take the C escapes, such as \n, \t, \\, \" and \0.

General-purpose registers are written $ and a number from 0 to 31, or $ and a name:

Floating-point registers are $f0-$f31, and condition codes are $fcc0-$fcc7 or a number from 0 to 7. Coprocessor 0 and floating-point control registers are written by number: $12 is Status in mfc0 $t0, $12, and $31 is FCSR in cfc1 $t0, $31.

Any integer operand is an expression over numbers, labels and constants, such as table+8 or end-start. Parentheses group subexpressions. The operators, from highest precedence to lowest, are:

1. Unary - and +
2. * and /, with / rounding toward zero
3. Binary + and -
4. >>, an arithmetic shift right

Operands such as shift amounts, bit-field positions and sizes, alignments, .space sizes, repeat counts, segment addresses, lui and trap immediates, and integer values in .float and .double take no labels. A constant defined earlier in the same file without labels works there.

name = expression or .set name, expression defines a constant.

ROWS = 16
COLS = ROWS * 2
	.data
grid:	.space	ROWS * COLS

Constants are scoped like labels, as Multiple files describes.

A segment directive switches to its segment, at the address it gives or where the segment left off:

The memory map shows how much of these ranges a program can use. Instructions go only in .text and .ktext, and data directives work in any segment. Items that overlap are an error.

spimbot assembles every file you give it into one program, in the order given. Each file starts in .text, and each segment continues where the previous file left it.

Labels and constants are local to their file. .globl name or .global name exports a name the file defines to every file, and a file's own definition takes precedence over an exported one. Exporting a name the file does not define, or a name another file already exports, is an error. main is exported from the first file that defines it unless a file exports it with .globl.

.comm name, size reserves size zeroed bytes for name at the next word-aligned address in .data and exports name. .lcomm does the same without exporting. Neither changes the current segment.

.extern name[, size] makes name global. When the file does not define name and no other file exports it, a nonzero size gives name zeroed storage in the 64 KiB small-data area at 0x10000000, which $gp addresses.

A data directive value can repeat as value:count: .word 0:8 is eight zero words, and .byte 1, 2:3 is the bytes 1, 2, 2, 2. A value that does not fit its directive's size is an error.

Each repetition of a .repeat block defines its labels and constants again, so a block that repeats more than once cannot define any.

.struct offset starts a layout in which labels name offsets from offset. Its data directives advance the offset and write no data, so their values must be zero. The layout ends at the next segment directive or the end of the file.

	.struct	0
point_x:	.word	0
point_y:	.word	0
point_size:

	.text
get_y:
	lw	$v0, point_y($a0)	# $a0 holds a point's address
	jr	$ra

Here point_y is 4 and point_size is 8. These names are labels, so point_y($a0) expands through $at.

The assembler accepts the MIPS32 Release 2 instruction set with its floating-point and coprocessor instructions. In the tables, rd, rs and rt are general-purpose registers, fd, fs, ft and fr floating-point registers, imm an immediate, sa a shift amount and addr a memory operand.

A bit field has at least 1 bit and fits in 32 bits: pos + size is at most 32.

sll, srl, sra and rotr take rd, rt, sa and shift or rotate right rt by the constant sa, 0 to 31. sllv, srlv, srav and rotrv take rd, rt, rs and shift or rotate by the low 5 bits of rs. Each shift and rotate assembles to its register or constant form to match the amount: sll rd, rt, rs is sllv. nop, ssnop and ehb take no operands and do nothing.

A branch reaches 32,768 instructions either way. For a farther target, use j.

j and jal reach the 256 MiB region of the instruction after the jump. For a farther target, use jr.

An indexed operand such as $t1($t0) has no space before the (. Alignment rules are in Bus errors and alignment. cache, pref, prefx, synci and sync assemble and do nothing.

teq rs, imm is teqi, and likewise for the other register traps.

Floating-point mnemonics end in a format: .s single, .d double or .w 32-bit integer.

The conditions are f, un, eq, ueq, olt, ult, ole and ule, and the signaling sf, ngle, seq, ngl, lt, nge, le and ngt, which also signal Invalid on a quiet NaN.

A double names an even register and the odd register after it. The 64-bit integer format .l and the paired-single format .ps run only with Status.FR set, as Bare mode and 64-bit registers describes. Rounding and exceptions are in Floating-point unit.

These forms of real instructions assemble to another real instruction or expand through $at:

• Two operands: addi $t0, 5 is addi $t0, $t0, 5. addi, addiu, slti, sltiu, andi, ori, xori, add, addu, sub, subu, and, or, xor, nor, slt, sltu, sllv, srlv and srav take this form.
• An immediate or label as the last operand of add, addu, sub, subu, and, or, xor, nor, slt, sltu, movz, movn and mul. A constant that fits the matching immediate instruction uses it: add $t0, $t1, 5 is addi $t0, $t1, 5. Any other value expands to li $at, value and the register instruction.
• An immediate as rt of mult, multu, div, divu, madd, maddu, msub, msubu, beq, bne, beql and bnel: 0 is $zero, and any other value goes into $at with li.
• A load or store address as offset(base), (base), label, label+offset, label(base) or an absolute address. A constant offset from -32,768 to 32,767 fits the instruction: lw $t0, 0x100 is lw $t0, 0x100($zero). A label or a larger offset expands to lui $at, high, then addu $at, $at, base when there is a base, then the access with the low half as offset.

Where the table says rt/imm, rt can be an immediate: 0 is $zero, and any other value goes into $at first with li $at, imm.

With a label, an offset that does not fit 16 bits, or a load whose base is its destination, ulw, ulh, ulhu, usw, ush, ld and sd put the address in $at first and access it at offset 0.

An instruction whose expansion uses $at cannot name $at in any operand, including a memory operand's base. The exceptions are the destinations of li, la, lb, lbu, lh, lhu, lw and ll. An instruction whose expansion does not use $at can name it anywhere.

check and exec take two assembler options. Matches always assemble bots with both off.

--bare requires each statement to be exactly one real instruction under its own mnemonic. Pseudo-instructions, forms that assemble to another instruction (add $t0, $t1, 5, jr label) and addresses that need $at are errors. Two-operand forms such as addi $t0, 5 are accepted.

--fp64 lets 64-bit floating-point operands name odd registers, for programs that set Status.FR to get 32 registers of 64 bits. See Floating-point unit.

The assembler reports every error at once, sorted by file, line and column, with the source line, carets under the problem and a note when a fix is likely. Errors that belong to no line, such as a missing main or overlapping items, come last. When there is any error, nothing runs.