RISC Lab Assembler

On the "RISC Lab" levels (part 5 of the course) the Assembler tab works differently from levels 18–29. It is now a true RV32I subset: 32 registers, 32-bit machine words, R/I/S/B/U/J formats. Every program line assembles into a word you can compare with the reference bitwise, and from level 54 you can also execute it cycle by cycle on the reference core.

The assembler grows with your schematic: build a new instruction at a level — the assembler learns it. Because of this design, an "unknown instruction" error is not a bug: check which level unlocks the instruction.

What a program looks like

# comment — everything after # is ignored
loop:                      # label — a name and a colon
  addi x5, x0, 3           # instruction, comma-separated operands
  addi x5, x5, -1          # numbers: decimal or 0x…
  bne  x5, x0, loop        # branches go to labels
.end                       # halt — a required line

• One instruction per line; empty lines and comment-only lines are skipped.
• Comments start with # (// and ; also work in level templates).
• Registers: x0…x31 plus the name ra (≡ x1). x0 always reads as 0.
• Numbers: decimal (-5) and hexadecimal (0x1F).
• The .end line is required — without it assembly gives ERR_ASM_NO_END. It may also sit in the middle of a program: the halt word lands at its own address and parsing continues.

Growth stages: which instruction comes from which level

At level 51 the manual "Word from fields" exercise replaces a schematic task: build the machine word from instruction fields and compare it with the assembler bitwise — you see exactly where each operand lives inside the word.

Instruction formats

Every instruction is one 32-bit word. Its fields are laid out in one of six formats:

Memory instructions use the "offset(register)" pair: lw x6, 0(x5) reads the word at address x5 + 0. The offset ranges from −2048 to 2047; lui takes 0…0xFFFFF.

Pseudo-instructions

Pseudo-instructions are convenient shorthands the assembler expands into real instructions:

li with a large number takes two words — label addresses below it shift by 4. Before level 55 a large li gives ERR_ASM_IMM_RANGE.

Branches and labels

• A label is a name of Latin letters, digits and _ not starting with a digit, declared on a line like name:.
• The beq/bne/jal offset counts bytes from the address of the branch instruction itself to the label. The assembler computes it — you only need the label.
• A branch target must be even (addresses go in steps of 4, so an odd target usually means a typo in the label): an odd target gives ERR_ASM_UNALIGNED_TARGET.
• beq/bne range is −4096…+4094 bytes; jal reaches ±1 MB.

Assembly errors

Errors appear under the editor with a line number. The text tells you what to check:

The assembler reports all errors at once, not just the first one — fix them top to bottom and press "Assemble" (Ctrl+Enter) again.

Execution from level 54

From level 54 "Assemble" not only builds the words but also executes the program on the reference single-cycle core: one instruction — one cycle. The "Execution" block shows registers, the cycle counter, and the instruction trace. Run-time errors (a misaligned address, a read from the instruction window, an address outside the data window) freeze the machine with an error code — they are documented in the Execution tab help.

• .end is the halt: it adds no cycle, the counter freezes.
• Data memory lives in the window 0x1000…0x13FF; the address step for lw/sw is exactly 4.
• The LED is at 0xFFFF_F000, write-only (appears at level 59); the switches at 0xFFFF_F004, read-only.

Example: a bne loop (level 54)

# x5 = 3; run the body 3 times
  addi x5, x0, 3      # x5 = 3 — the counter
loop:
  addi x5, x5, -1     # x5 -= 1
  bne  x5, x0, loop   # while x5 != 0 — jump back
.end

The last bne executes but does not jump: x5 is already 0. A loop of N iterations costs N×(body + 1) cycles.

Example: a data base with lui (level 55)

# read a word from the data array at 0x1000
  lui  x10, 0x1       # x10 = 0x1000 — the array base
  lw   x6, 0(x10)     # x6 = the first word of the array
.end

lui places a number into the upper 20 bits: lui x10, 0x1 yields 0x1000, because the value is shifted 12 bits left.