1.1 — THE CENTRAL QUESTION

You write text. The CPU executes bits. Something in the middle does the translation. But what? Most people collapse this entire process into one word — "compile" — and that's where the confusion starts.

There are actually four separate tools in the classic pipeline, each doing something fundamentally different. Let's name them and understand them before we look at the MIPS16 reference tool specifically.

1.2 — THE FOUR TOOLS

The compiler: the smart one

The compiler is the only tool that understands what your program means. It parses grammar, enforces types, detects logical errors (int x = "hello" fails here), and applies optimizations. Its output is not an executable — it's assembly text. On its own, nothing runs.

The assembler: the mechanical translator

The assembler does zero semantic analysis. It reads assembly mnemonics and applies a lookup table. ADD is always opcode 0b0000. Period. It cannot catch logic errors. It cannot optimize. Its only "intelligence" is resolving label addresses — figuring out that when you write BEQ $r4, LOOP, the address of LOOP is word address 6. That single task requires the two-pass algorithm we'll study in Module 3.

The linker: the glue

When you call printf() in C, the assembler produces a placeholder — it doesn't know where printf lives. The linker's job is to stitch together all the object files (your code + standard library) and resolve these cross-file references. The MIPS16 reference assembler skips this step entirely because it is single-file — everything is resolved by the assembler itself.

1.3 — YOUR MIPS16 TOOL IN CONTEXT

The reference MIPS16 tool combines two things: an assembler (the assemble() function) and an emulator (the stepCPU() function). You type assembly text → the assembler converts it to an array of 16-bit words → the emulator fetches and executes those words one by one.

This pattern — self-contained assembler-emulator — is how educational processors work (LC-3, MARIE), and how embedded microcontroller tools worked in the 1980s-90s.

1.4 — IS AN ASSEMBLER A COMPILER?

Technically, an assembler is a compiler in the broad Computer Science sense (any program that translates from one language to another). But in practice, when engineers say "compiler" they mean a tool that understands semantics and transforms across abstraction levels. An assembler is categorically simpler — it's closer to a structured find-and-replace than a real compiler.

The clearest test: can the tool catch a semantic error? A compiler catches if (x = 5) (assignment where comparison was intended). An assembler cannot — if your logic is wrong, the assembler happily encodes your bug into bits.

2.1 — WHAT IS AN ISA?

An Instruction Set Architecture (ISA) is the contract between software and hardware. It defines exactly: which operations the CPU can perform, how instructions are encoded as bits, how many registers exist, how memory is addressed, and how control flow works.

The MIPS16 ISA defined in the reference tool is a pedagogical 16-bit architecture. Every design decision is visible and motivated. Let's read it from the source code.

2.2 — REGISTERS

MIPS16 has 16 registers, each 16 bits wide. They are numbered r0–r15 and have conventional aliases:

2.3 — THE TWO INSTRUCTION FORMATS

Every MIPS16 instruction is exactly 16 bits. The top 4 bits are always the opcode. The remaining 12 bits depend on the format:

R-Format (Register)

Used by arithmetic/logic instructions that operate on registers.

Example: ADD $r2, $r1, $r3 → opcode=0000, Rd=0010, Rs=0001, Rt=0011 → 0x0213

I-Format (Immediate)

Used by memory, branch, and load-immediate instructions. The second source is a signed 8-bit constant baked into the instruction itself.

Example: ADI $r2, 5 → opcode=1101, Rd=0010, Im8=00000101 → 0xD205

2.4 — ALL 16 INSTRUCTIONS

The ISA is defined in the const ISA = {...} object in the source. Here is every instruction, its opcode, format, and exact operation:

* SRL and JLR use R-format encoding but have special behavior. JLR ignores Rt.

2.5 — MEMORY MODEL

MIPS16 uses word addressing — each address refers to one 16-bit word, not one byte. So address 0x0001 is the second word (bytes 2–3). This is different from byte-addressed architectures like x86. The emulator displays addresses in byte terms (×2) for compatibility, but internally everything is word-addressed.

2.6 — BRANCH ADDRESSING

BEQ and BNE use PC-relative addressing. The Im8 field is a signed offset added to PC+1. So BEQ $r4, -3 jumps to 3 words before the next instruction — which is a backwards loop.

In the assembler: when you write BEQ $r4, LOOP, the assembler computes Im8 = address(LOOP) − (current_word_address + 1). This is done in Pass 2 using the labelMap built in Pass 1.

2.7 — THE SPECIAL CASES: LUI + ADI

Since Im8 is only 8 bits, you cannot load an arbitrary 16-bit value in one instruction. The solution is two instructions working together:

; Load 0xBEEF into $r1
LUI $r1, 0xBE    ; $r1 = 0xBE00  (shift left 8)
ADI $r1, -17    ; $r1 = 0xBE00 + (-17) = 0xBDEF... wait

There's a subtlety: if the low byte is ≥ 128, it will sign-extend to negative when used as Im8. So the assembler's LI pseudo-instruction adjusts the high byte upward by 1 to compensate. This is exactly what the expandPseudo function does for LI.

3.1 — WHY TWO PASSES?

Here's the fundamental problem. You're writing this program:

BEQ $r4, DONE     ; jump to DONE — but where IS Done?
ADD $r1, $r2, $r3
DONE: JLR $r0, $r15

When the assembler reads line 1, it hasn't seen DONE: yet. It doesn't know the address. This is the forward reference problem — you're referencing a label that's defined later in the file.

The solution is to read the file twice:

3.2 — PASS 1: TOKENISATION AND LABEL COLLECTION

Pass 1 iterates over every line, doing three things:

1. Strip comments — stripComment() removes everything after ; or #, respecting quoted strings.
2. Extract labels — anything before a : gets added to labelMap with the current word address.
3. Count words — figure out how many 16-bit words each line emits, and advance the address counter. This is where expandPseudo() is called to check if a pseudo-instruction expands to 1 or 2 real instructions.

3.3 — PASS 2: ENCODING

Pass 2 iterates over tokList (not the raw source again). Now it has the complete labelMap, so every forward reference can be resolved. For each instruction:

1. Look up the mnemonic in ISA to get the opcode and format.
2. If R-format: parse three register operands, pack as (op<<12)|(Rd<<8)|(Rs<<4)|Rt.
3. If I-format: parse register + immediate, resolve labels, pack as (op<<12)|(Rd<<8)|Im8.
4. Push the result word into the program[] array.

Encoding R-format — from the source

// From assemble(), Pass 2, R-format branch:
const Rd = parseReg(a[0]), Rs = parseReg(a[1]);
const Rt = m==="JLR" ? 0 : parseReg(a[2]||"$r0");
word = ((op & 0xF) << 12) | ((Rd & 0xF) << 8)
     | ((Rs & 0xF) << 4)  |  (Rt & 0xF);

Encoding I-format branch offset

// BEQ/BNE: offset = target_address − (current_word_address + 1)
imm = combined[lbl] - (wa + 1);
// wa = current word address, combined = labelMap merged with equMap

3.4 — THE COMPLETE ASSEMBLY PIPELINE

4.1 — WHAT IS A PSEUDO-INSTRUCTION?

A pseudo-instruction is a mnemonic that looks like a real instruction but isn't — the CPU has no opcode for it. The assembler expands it into one or more real instructions before encoding. This is pure syntactic sugar: makes code more readable, generates real bits.

4.2 — THE FIVE PSEUDO-INSTRUCTIONS

4.3 — ASSEMBLER DIRECTIVES

Directives are not instructions at all — they're commands to the assembler itself about how to organize the output. They produce no CPU opcodes (except .word/.space/.asciiz which emit data words).

Example: placing data at a specific address

        .org  0x0000         ; code starts at word 0

_start:
        LI   $fp, 0x0020    ; point $fp at our buffer
        LDW  $t0, 0          ; load first word of buffer
        JLR  $r0, $r15       ; halt

        .org  0x0020         ; data section at word 0x20
msg:    .asciiz "Hi!"        ; 4 words: 'H','i','!',0x00
val:    .word   0xBEEF       ; 1 word: 0xBEEF

5.1 — THE FETCH-DECODE-EXECUTE CYCLE

Every CPU, from your laptop to a microcontroller, runs the same basic loop indefinitely:

1. Fetch — read the instruction word at address PC from memory
2. Decode — split the 16-bit word into fields (op, Rd, Rs, Rt, Im8)
3. Execute — perform the operation, update registers/memory/PC

In stepCPU() this happens in one JavaScript function call per instruction. The state object ({regs, mem, pc}) is immutable — each call returns a new state object. This is clean functional-style emulation.

5.2 — DECODING A WORD

// From stepCPU() — first thing after fetching:
const word = imem[pc];
const op  = (word >> 12) & 0xF;   // top 4 bits
const Rd  = (word >>  8) & 0xF;   // bits 11–8
const Rs  = (word >>  4) & 0xF;   // bits 7–4
const Rt  =  word        & 0xF;   // bits 3–0
const im8b =  word        & 0xFF;  // bits 7–0 (unsigned)
const Im8s =  sx8(im8b);           // sign-extended

5.3 — THE UNIFIED DATAPATH

Rather than a giant switch on opcode, stepCPU() uses a clever unified datapath: it computes a set of intermediate signals that are then muxed (selected) based on the opcode. This mirrors real hardware:

5.4 — KEY CONTROL SIGNALS

// alufnOvr — overrides ALU function for non-ALU ops:
// LDW/STW/ADI → use ADD (0000) to compute address/value
// BEQ/BNE → use SUB (0001) to test zero
// LUI/JLR → null (ALU not used)
const alufnOvr =
  [0b1000,0b1001,0b1101].includes(op) ? 0b0000  // ADD
: [0b1010,0b1011].includes(op)         ? 0b0001  // SUB
: [0b1100,0b1111].includes(op)         ? null
: op;                                              // use op directly

// werf — write enable to register file
// STW, BEQ, BNE don't write to registers
const werf = ![0b1001,0b1010,0b1011].includes(op);

5.5 — MMIO: MEMORY-MAPPED I/O

Instead of special I/O instructions, MIPS16 puts I/O devices at specific memory addresses. Read/write those addresses and you talk to the device. The emulator intercepts LDW/STW at four magic word addresses:

6.1 — CALLING CONVENTIONS

When you call a function in MIPS16 assembly, both caller and callee must agree on how to pass arguments, return values, and preserve registers. This informal agreement is the calling convention.

6.2 — THE STACK FRAME

The stack grows downward (lower addresses). ADI $sp, -1 allocates one word on the stack. ADI $sp, 1 frees it. This is word-addressed, so each "slot" is one 16-bit word.

6.3 — ANNOTATED EXAMPLE: SUM 1..N

; Sum integers 1..N, result in $a0
; Uses: $t0=counter, $t1=sum, $t2=N

        LUI  $r1, 0        ; $t0 = 0  (counter)
        ADI  $r1, 0
        LUI  $r2, 0        ; $t1 = 0  (sum)
        ADI  $r2, 0
        LUI  $r3, 0        ; $t2 = 8  (N)
        ADI  $r3, 8

LOOP:   ADI  $r1, 1        ; counter++
        ADD  $r2, $r2, $r1 ; sum += counter
        SUB  $r4, $r3, $r1 ; temp = N - counter
        BNE  $r4, LOOP     ; if temp≠0: loop
                            ; (BNE branches if Rd ≠ 0)
        ADD  $r9, $r2, $r0 ; $a0 = sum
        JLR  $r0, $r15     ; return / halt

6.4 — BUILDING A FUNCTION WITH STACK DISCIPLINE

; putchar($a0) — write one character to terminal
putchar:
        ADI  $sp, -1       ; allocate 1 stack slot
        MOV  $fp, $sp      ; $fp points to frame
        STW  $ra, 0        ; save return address

pc_poll:
        LI   $t0, 0x7FFA   ; $t0 = OUT_STATUS address
        MOV  $fp, $t0      ; use $fp for LDW base
        LDW  $t1, 0        ; read OUT_STATUS
        MOV  $fp, $sp      ; restore $fp
        BEQ  $t1, pc_poll  ; loop while not ready

        LI   $t0, 0x7FFB   ; $t0 = OUT_DATA address
        MOV  $fp, $t0
        STW  $a0, 0        ; write char
        MOV  $fp, $sp

        LDW  $ra, 0        ; restore $ra
        ADI  $sp, 1        ; free stack slot
        MOV  $fp, $sp
        JR   $ra            ; return

REGISTERS

R-FORMAT INSTRUCTIONS (op bits 15–12)

I-FORMAT INSTRUCTIONS

PSEUDO-INSTRUCTIONS

MMIO ADDRESSES (word addresses)

DIRECTIVES

Independent Project

This study tool is an independent project developed for pedagogic purposes in the context of Computer Architecture at . It is provided AS IS, without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement.

No Endorsement

No institution or individual has endorsed, reviewed, sponsored, or approved this tool in any way.

No Guarantees

The content of this tool — including quiz questions, module text, assembler behavior, and emulator output — may contain errors or omissions. It is not a substitute for official course materials, lectures, or instructor guidance. Always refer to official sources for authoritative information.

Limitation of Liability

The author assumes no liability for any direct, indirect, incidental, or consequential damages arising from the use or inability to use this tool, including but not limited to errors in educational content, loss of progress data, or any reliance placed on this material in an academic context.

Intellectual Property

The MIPS16 ISA definition, assembler specification, and emulator design referenced in this tool are based on standard computer-architecture course materials. All rights to those materials remain with their respective owners. This tool does not claim ownership of any third-party intellectual property.

Open Use

This tool is shared freely for educational use. If you find it useful, please use it responsibly and do not misrepresent it as an official course resource.