RISC-V assembly

Develop locally · Develop hosted · Read a trace

Write your robot in real RISC-V assembly: the RV32IMFD instruction set, with the standard ilp32d calling convention, the code a RISC-V chip runs. Your .s file is the robot. LLVM assembles and links it, and it runs on a small RISC-V machine that Clunkyard built for robots, inside the same sandbox as every WebAssembly robot and metered the same way. Because we built the machine, it can tell you exactly what went wrong: a bad load or jump stops the robot with the instruction, its source line and the registers that led there.

This guide assumes you have never written assembly. It explains registers, memory, calls and the stack as they work in this machine, then builds a robot one step at a time, ending at the starter. Every example here is assembled and run by the arena's tests, so what you read is what the machine does. RISC-V in ten minutes is the one-page summary, and the reference at the end lists every call.

Your first robot

# Drive in a circle and sweep the scanner around.
.include "clunkyard.inc"          # the names for every robot call

.text                             # code goes in the .text section
.globl clunkyard_turn             # make the label visible to the machine
clunkyard_turn:                   # the machine calls this once a turn
    li t0, 1                      # t0 = 1
    fcvt.d.w fa0, t0              # fa0 = 1.0, a double
    cy_drive_throttle             # full speed: the call reads fa0
    li t0, 2
    fcvt.d.w fa0, t0
    fdiv.d fa0, fa0, fa0          # 2.0 / 2.0 = 1.0
    cy_drive_turn                 # turn hard left
    li a0, 0                      # status 0: play on
    ret                           # back to the machine

Each line is one instruction, a directive (starting with .), or a label (ending in :). # starts a comment. The machine calls clunkyard_turn once a turn, like a function: it starts at the label and runs until ret returns to the machine. Putting 0 in a0 before returning means "play on"; anything else ends the robot. A program may also have clunkyard_start, which the machine calls once, before the first turn.

The cy_ lines are calls to the robot: each one is a macro from clunkyard.inc that puts a call number in register a7 and runs ecall, the instruction that asks the machine for something. The arguments are already in registers: cy_drive_throttle takes its one number from fa0.

Registers

A RISC-V processor computes in registers: 32 integer registers, each holding one 32-bit word, and, with the F and D extensions, 32 floating-point registers, each holding one 64-bit double. Instructions take their inputs from registers and put their result in one; only loads and stores touch memory. Every register has a number (x0 to x31, f0 to f31) and a name that says what the calling convention uses it for. Write the names: the assembler accepts both.

Name Register What it is for Kept across a call?
zero x0 always 0; writes to it vanish
ra x1 the return address no
sp x2 the stack pointer yes
gp, tp x3, x4 reserved; leave them alone
t0 to t6 x5–x7, x28–x31 temporaries no
s0 to s11 x8, x9, x18–x27 saved registers yes
a0 to a7 x10–x17 arguments and results no
ft0 to ft11 f0–f7, f28–f31 floating-point temporaries no
fs0 to fs11 f8, f9, f18–f27 floating-point saved registers yes
fa0 to fa7 f10–f17 floating-point arguments and results no

The calling convention is the agreement that lets functions call each other. The few rules that matter here:

The robot calls are kinder than functions: an ecall changes only a0 (the status) and a7 (the call number), so every other register keeps its value across cy_ calls.

The instructions a robot needs

RISC-V instructions name their destination first: add t0, t1, t2 means t0 = t1 + t2. Instructions ending in i take a 12-bit immediate, a number from -2048 to 2047 written in the instruction. A few common instructions are pseudo-instructions the assembler turns into real ones: li (load any 32-bit number), la (load a label's address), mv, j, call, ret, beqz, bnez, fmv.d, fneg.d and fabs.d.

    li t0, 1000            # t0 = 1000
    addi t1, t0, -1        # t1 = t0 - 1
    add t2, t0, t1         # t2 = t0 + t1
    sub t2, t2, t1         # t2 = t2 - t1
    slli t3, t0, 2         # t3 = t0 * 4, a shift left by 2
    mul t3, t3, t0         # t3 = t3 * t0
    li t4, 7
    div t5, t3, t4         # t5 = t3 / 7, rounded towards zero
    rem t6, t3, t4         # t6 = the remainder
    mv a1, t6              # copy a register
    seqz a2, t6            # a2 = 1 if t6 is 0, else 0
    slt a3, t1, t0         # a3 = 1 if t1 < t0 (signed), else 0

Division never traps: dividing by zero gives -1 (all ones) and the remainder is the dividend.

Branches compare two registers and jump to a label when the test holds: beq, bne, blt, bge (signed), bltu, bgeu (unsigned), and the one-register forms beqz, bnez, bltz and bgez. A number followed by a colon, such as 1:, is a local label; 1b jumps to the nearest 1: backward and 1f to the nearest forward, so short loops need no names.

    # Add 1 + 2 + ... + 10 into t1.
    li t0, 10              # the counter
    li t1, 0               # the sum
1:  add t1, t1, t0
    addi t0, t0, -1
    bnez t0, 1b            # go round again until the counter is 0
    # if t1 >= 50 then t2 = 1 else t2 = 2
    li t3, 50
    blt t1, t3, 2f
    li t2, 1
    j 3f
2:  li t2, 2
3:

Doubles

Every number the robot API gives or takes is a double: headings and pitches in degrees, ranges in arena units, battery charge. The D extension computes with them in the f registers.

    li t0, 3
    fcvt.d.w ft0, t0       # integer to double: ft0 = 3.0
    li t0, 4
    fcvt.d.w ft1, t0       # ft1 = 4.0
    fmul.d ft2, ft0, ft0   # 9.0
    fmadd.d ft2, ft1, ft1, ft2   # ft1 * ft1 + ft2 = 25.0, rounded once
    fsqrt.d ft3, ft2       # 5.0
    fdiv.d ft4, ft3, ft1   # 1.25
    fsub.d ft4, ft4, ft0   # -1.75
    fabs.d ft5, ft4        # 1.75
    fneg.d ft6, ft5        # -1.75
    fmin.d ft7, ft5, ft6   # -1.75, the smaller
    flt.d t1, ft6, ft5     # t1 = 1 if ft6 < ft5: comparisons give 0 or 1
    feq.d t2, ft4, ft6     # t2 = 1, they are equal
    fcvt.w.d t3, ft3, rtz  # double to integer, rounded towards zero: 5

There are no floating-point immediates: a constant such as 0.7 lives in memory, and you load it (the next section shows how). Small whole numbers are often quicker with li and fcvt.d.w, as above. Converting a double to an integer takes a rounding mode: rtz truncates like C, rne rounds to nearest. .d instructions work on doubles; the .s forms work on singles, which the robot API never uses.

Memory

Your program, its data and its stack share one megabyte of memory, from address 0x00000000 to 0x000fffff. Each 4 KiB page is either code, read only, read and write, or not there at all:

Addresses What is there
0x00000000 to 0x0000ffff nothing: reading or writing here faults, which catches null pointers
0x00010000 on your program: .text (code, which can run but not be written), then .rodata (constants, read only), then .data and .bss (read and write)
up to 0x000d0000 the most your program may take
0x000e0000 to 0x000fffff the stack, 128 KiB; sp starts at the top, 0x00100000

Sections are where you put things: .text for code, .rodata for constants, .data for variables with a starting value and .bss for variables that start at zero. Memory keeps its contents between turns, so .data and .bss are how a robot remembers. Registers do not: each turn starts with every register zero but sp and ra.

A load copies from memory into a register and a store from a register into memory, at an address written as an offset from a register: lw t1, 8(t0) loads the 4-byte word at t0 + 8. lw and sw move words, lb and sb bytes, and fld and fsd doubles. An access must be aligned: a word's address a multiple of 4 and a double's a multiple of 8. .balign 8 before a label puts it on an 8-byte boundary.

# Count the turns in memory, and keep constants in .rodata.
.include "clunkyard.inc"

.section .rodata
.balign 8
SEVEN_TENTHS: .double 0.7          # a constant double

.section .data
.balign 4
turns: .word 0                     # a word that starts at 0

.text
.globl clunkyard_turn
clunkyard_turn:
    la t0, turns                   # t0 = the address of turns
    lw t1, 0(t0)                   # load the count
    addi t1, t1, 1
    sw t1, 0(t0)                   # store it back: it is there next turn
    la t0, SEVEN_TENTHS
    fld fa0, 0(t0)                 # fa0 = 0.7
    cy_drive_throttle
    li a0, 0
    ret

The stack

The stack is memory a function borrows while it runs: it moves sp down to make room, stores what it must keep, and moves sp back before it returns. A function that calls another function keeps ra there:

.include "clunkyard.inc"

.text
# twice(fa0) -> fa0 * 2, a leaf: it calls nothing, so it needs no stack.
twice:
    fadd.d fa0, fa0, fa0
    ret

# four_times(fa0) -> fa0 * 4: it calls twice, so it saves ra.
four_times:
    addi sp, sp, -16               # room for 16 bytes, keeping sp a multiple of 16
    sw ra, 12(sp)                  # save the return address
    call twice                     # ra now points here, inside four_times
    call twice
    lw ra, 12(sp)                  # put the return address back
    addi sp, sp, 16
    ret

.globl clunkyard_turn
clunkyard_turn:
    addi sp, sp, -16
    sw ra, 12(sp)
    li t0, 1
    fcvt.d.w fa0, t0
    call four_times                # fa0 = 4.0
    lw ra, 12(sp)
    addi sp, sp, 16
    li a0, 0
    ret

clunkyard_turn is a function too: the machine called it, and ra holds the way back, so it saves ra before it calls anything with call.

Calling the robot

Every call to the robot is a cy_ macro from clunkyard.inc. Before the macro, put the call's arguments in registers: integers and addresses in a0, a1, ... in order, and doubles in fa0, fa1, ... in order. The reference below gives each call's registers, and so does the comment above its macro in clunkyard.inc. The call's status comes back in a0: 0 (CY_OK) when it answered, 1 (CY_NONE) when there is nothing to answer with, such as no robot in sight, and a negative number for an error.

A call that answers with a value writes it to memory, at an address you pass. cy_me_heading takes one argument, the address of 8 bytes for the heading:

.include "clunkyard.inc"

.section .bss
.balign 8
HEADING: .zero 8                   # 8 bytes for one double

.text
.globl clunkyard_turn
clunkyard_turn:
    la a0, HEADING                 # where to write the heading
    cy_me_heading                  # writes it; a0 = the status
    la t0, HEADING
    fld fa0, 0(t0)                 # fa0 = this robot's heading, in degrees
    cy_scanner_heading             # point the scanner the same way
    li a0, 0
    ret

A call that answers CY_NONE leaves your memory as it was, so check the status, or clear the memory first.

Reading a record

Some answers are records: several fields laid out in memory one after another. A contact, a robot the sensors detect, has a slot number, a range, a bearing, an elevation and more. clunkyard.inc gives each record's size and each field's offset from the record's start: CY_CONTACT_SIZE is 72 bytes, and CY_CONTACT_RANGE is 8, so the range is the double at the record's address plus 8.

.include "clunkyard.inc"

.section .bss
.balign 8                          # records hold doubles: align them to 8
TARGET: .zero CY_CONTACT_SIZE      # room for one contact

.text
.globl clunkyard_turn
clunkyard_turn:
    la a0, TARGET
    cy_sensors_nearest             # the nearest precise contact, if any
    bnez a0, 1f                    # CY_OK is 0: anything else means none
    la t0, TARGET
    fld fa0, CY_CONTACT_BEARING(t0)   # the field at TARGET + its offset
    cy_gun_aim_heading             # turn the turret towards it
    lw t1, CY_CONTACT_SLOT(t0)     # an integer field: a word
1:  li a0, 0
    ret

fld fa0, CY_CONTACT_BEARING(t0) is the whole idea: the base address in a register and the field's offset written in the instruction. A record inside a record, such as a zone's centre, has an offset of its own (CY_ZONE_CENTER), and so does each of its fields (CY_ZONE_CENTER_X). A call that takes a record, such as cy_angles_bearing_to, takes its address: la a1, ZONE + CY_ZONE_CENTER passes the centre inside ZONE.

A robot, step by step

Each step adds one idea and plays a match as it is.

1. Search: drive, turn and sweep the scanner

The scanner sees robots in an arc. Sweeping it around finds them; the scanner remembers where it last pointed, and cy_scanner_last reads that back.

.include "clunkyard.inc"

.macro fload freg, label           # a double constant from .rodata
    la t6, \label
    fld \freg, 0(t6)
.endm

.section .rodata
.balign 8
CRUISE: .double 0.5
LEFT:   .double 0.33
ARC:    .double 40.0
STEP:   .double 36.0

.section .bss
.balign 8
SCAN: .zero CY_SCAN_SIZE

.text
.globl clunkyard_turn
clunkyard_turn:
    fload fa0, CRUISE
    cy_drive_throttle
    fload fa0, LEFT
    cy_drive_turn
    la a0, SCAN
    cy_scanner_last                # where the scanner pointed last turn
    la t0, SCAN
    fld fa0, CY_SCAN_HEADING(t0)
    fload ft0, STEP
    fadd.d fa0, fa0, ft0           # 36 degrees on
    cy_scanner_heading
    fload fa0, ARC
    cy_scanner_arc                 # a 40-degree beam
    li a0, 0
    ret

fload is a macro of our own: .macro names a few lines and \freg and \label are its arguments, so fload fa0, CRUISE becomes the la and fld beneath it. The starter uses the same one.

2. Find a robot and aim at it

When a robot is in the beam, cy_sensors_nearest writes its contact. Point the turret at its bearing and elevation; otherwise keep searching.

.include "clunkyard.inc"

.macro fload freg, label
    la t6, \label
    fld \freg, 0(t6)
.endm

.section .rodata
.balign 8
CRUISE: .double 0.5
LEFT:   .double 0.33
ARC:    .double 40.0
STEP:   .double 36.0

.section .bss
.balign 8
SCAN:   .zero CY_SCAN_SIZE
TARGET: .zero CY_CONTACT_SIZE

.text
.globl clunkyard_turn
clunkyard_turn:
    la a0, TARGET
    cy_sensors_nearest
    bnez a0, search
    la t0, TARGET
    fld fa0, CY_CONTACT_BEARING(t0)
    cy_gun_aim_heading
    fld fa0, CY_CONTACT_ELEVATION(t0)  # t0 survives the call: ecall keeps it
    cy_gun_aim_pitch
    fld fa0, CY_CONTACT_BEARING(t0)
    cy_scanner_heading             # keep the beam on it
    j done
search:
    fload fa0, CRUISE
    cy_drive_throttle
    fload fa0, LEFT
    cy_drive_turn
    la a0, SCAN
    cy_scanner_last
    la t0, SCAN
    fld fa0, CY_SCAN_HEADING(t0)
    fload ft0, STEP
    fadd.d fa0, fa0, ft0
    cy_scanner_heading
    fload fa0, ARC
    cy_scanner_arc
done:
    li a0, 0
    ret

3. Fire when the turret is on target

The turret turns at a limited rate, so fire only once it points within a few degrees of the target, and only when the gun can fire with battery to spare: cy_gun_aim_now writes where it points now, and cy_gun_can_fire writes 1 when a shot of that power would leave the battery the spare you name. This step keeps the turn in saved registers (s1, fs0), which it saves and restores, because it calls a function.

.include "clunkyard.inc"

.macro fload freg, label
    la t6, \label
    fld \freg, 0(t6)
.endm

.section .rodata
.balign 8
POWER:     .double 2.0
SPARE:     .double 10.0
ON_TARGET: .double 3.0

.section .bss
.balign 8
NUMBER: .zero 8
WHOLE:  .zero 8
TARGET: .zero CY_CONTACT_SIZE
NOW:    .zero CY_DIRECTION_SIZE

.text
# angle_diff(fa0 target, fa1 current) -> fa0, from -180 to 180.
angle_diff:
    la a0, NUMBER
    cy_angles_angle_diff
    la t0, NUMBER
    fld fa0, 0(t0)
    ret

.globl clunkyard_turn
clunkyard_turn:
    addi sp, sp, -16
    sw ra, 12(sp)
    sw s1, 8(sp)
    fsd fs0, 0(sp)
    la a0, TARGET
    cy_sensors_nearest
    bnez a0, done
    la s1, TARGET                  # s1 survives the call below
    fld fs0, CY_CONTACT_BEARING(s1)
    fmv.d fa0, fs0
    cy_gun_aim_heading
    fld fa0, CY_CONTACT_ELEVATION(s1)
    cy_gun_aim_pitch
    fmv.d fa0, fs0
    cy_scanner_heading
    la a0, NOW
    cy_gun_aim_now                 # where the turret points now
    fmv.d fa0, fs0
    la t0, NOW
    fld fa1, CY_DIRECTION_HEADING(t0)
    call angle_diff                # how far it has to go
    fabs.d fa0, fa0
    fload ft0, ON_TARGET
    flt.d t1, fa0, ft0
    beqz t1, done                  # still turning: hold fire
    fload fa0, POWER
    fload fa1, SPARE
    la a0, WHOLE
    cy_gun_can_fire
    la t0, WHOLE
    lw t1, 0(t0)
    beqz t1, done                  # not loaded, or not enough battery
    cy_gun_fire
    fload fa0, POWER
    cy_gun_power
done:
    fld fs0, 0(sp)
    lw s1, 8(sp)
    lw ra, 12(sp)
    addi sp, sp, 16
    li a0, 0
    ret

4. Earn the bearing

A contact's bearing is only as good as the beam that saw it: its error, CY_CONTACT_BEARING_ERROR, is a fixed share of the arc. A wide beam finds a robot; a narrow one aims at it. So once a robot is in the beam, halve the arc each turn down to a few degrees, and fire only when the error across the line of sight, range × error in radians, is small. Add this to step 3 after the contact is read, and fire only when t1 is 1:

    # A contact 300 units out with a bearing error of 0.5 degrees: in a
    # robot, these come from the contact's own fields.
    li t1, 300
    fcvt.d.w ft0, t1               # range
    li t1, 1
    fcvt.d.w ft1, t1
    li t1, 2
    fcvt.d.w ft2, t1
    fdiv.d ft1, ft1, ft2           # bearing error, 0.5 degrees
    fmul.d ft3, ft0, ft1           # range × error
    li t1, 573
    fcvt.d.w ft4, t1
    li t1, 10
    fcvt.d.w ft5, t1
    fdiv.d ft4, ft4, ft5           # 57.3 degrees a radian
    fdiv.d ft3, ft3, ft4           # units across the line of sight: 2.6
    li t1, 12
    fcvt.d.w ft5, t1
    flt.d t1, ft3, ft5             # t1 = 1: precise enough to fire

The starter does this with the arc it scanned with (cy_scanner_last) and a beam held 60 units across at the target's range.

5. The starter

The starter in a new project puts these together and adds what keeps a robot alive: it leads a target that holds its course (cy_gun_lead), picks a shot's power from the range (cy_gun_power_for_flight_time), looks again where it last saw a robot (cy_tracker_last_seen, cy_tracker_position), follows a passive cue (cy_tracker_cue), swerves for half a second when it hears a shot (cy_sensors_cues), drives gently when the battery is low, steps out of the storm (cy_nav_storm) and heads back into the safe zone in sudden death (cy_nav_zone). Its comments explain each part; read it next.

Common mistakes, and what the fault says

When the machine cannot go on, the robot stops with RISCV_FAULT and a message that says what happened, the label and offset of the instruction, its line in your source, and the registers that led there. The match result, npx @clunkyard/cli match's output and the replay all show it.

A null pointer. A record address that was never set is 0, and the first 64 KiB are not mapped:

# expect: RISCV_FAULT
.include "clunkyard.inc"
.text
.globl clunkyard_turn
clunkyard_turn:
    li t0, 0                       # meant to be la t0, TARGET
    fld fa0, CY_CONTACT_RANGE(t0)
    li a0, 0
    ret
8-byte load from 0x00000008, near 0: a null pointer? at clunkyard_turn+0x4 (bot.s:7: fld fa0, CY_CONTACT_RANGE(t0)); t0=0x00000000 sp=0x00100000 ra=0xfffffff0

Read it from the left: what (an 8-byte load), the address, the machine's guess, where (clunkyard_turn+0x4 is 4 bytes, one instruction, into the label, at line 7), and the register the address came from.

A double that is not aligned. A record after a 4-byte word, without .balign 8, starts on a 4-byte boundary:

# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .bss
COUNT:  .zero 4
TARGET: .zero CY_CONTACT_SIZE      # needs .balign 8 before it
.text
.globl clunkyard_turn
clunkyard_turn:
    la t0, TARGET
    fld fa0, CY_CONTACT_RANGE(t0)
    li a0, 0
    ret
8-byte load from 0x0001100c, which is not a multiple of 8 at clunkyard_turn+0x8 (bot.s:10: fld fa0, CY_CONTACT_RANGE(t0)); t0=0x00011004 sp=0x00100000 ra=0xfffffff0

A missing ret. Without it, the processor runs on into whatever comes next, here the end of the code:

# expect: RISCV_FAULT
.include "clunkyard.inc"
.text
.globl clunkyard_turn
clunkyard_turn:
    li a0, 0
ran past the end of the code (a missing ret?) at clunkyard_turn (bot.s:6: li a0, 0); sp=0x00100000 ra=0xfffffff0

A lost return address. A function that calls another without saving ra returns to itself, forever, until the turn's fuel runs out (WASM_TURN_FUEL). If a turn never ends, look for a call in a function that does not save ra.

Writing a constant. .rodata is read only:

# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .rodata
.balign 4
LIMIT: .word 10
.text
.globl clunkyard_turn
clunkyard_turn:
    la t0, LIMIT
    sw zero, 0(t0)                 # constants cannot change
    li a0, 0
    ret
4-byte store to 0x00011000, which is read-only (code or constants) at clunkyard_turn+0x8 (bot.s:10: sw zero, 0(t0)); t0=0x00011000 sp=0x00100000 ra=0xfffffff0

A temporary after a call. t and ft registers may change in any function you call (though not in a cy_ call): keep values you need afterwards in s and fs registers. This one does not fault; it just computes with the wrong number.

Forgetting .globl. The build says so: clunkyard_turn must be global: add .globl clunkyard_turn.

A bad pointer to a call. A call that writes a record needs room for all of it in writable memory:

# expect: RISCV_FAULT
.include "clunkyard.inc"
.section .bss
.balign 8
TARGET: .zero CY_CONTACT_SIZE
.text
.globl clunkyard_turn
clunkyard_turn:
    la a0, TARGET                  # the contact to lead
    li a1, 0                       # meant to be la a1, AIM
    cy_gun_lead
    li a0, 0
    ret
ecall gun_lead_v1: a1 = 0x00000000 must point to 24 writable bytes, near 0: a null pointer? at clunkyard_turn+0x10 (bot.s:11: cy_gun_lead); sp=0x00100000 ra=0xfffffff0

Seeing what your robot does

ebreak is a trace point: it adds a line to the turn's debug log with where it is and the values in a0 and fa0, and the robot carries on. Put the value you want to see in a0 (a whole number) or fa0 (a double) first:

.include "clunkyard.inc"
.section .bss
.balign 8
HEADING: .zero 8
.text
.globl clunkyard_turn
clunkyard_turn:
    la a0, HEADING
    cy_me_heading
    la t0, HEADING
    fld fa0, 0(t0)
    li a0, 1                       # a marker: the first trace point
    ebreak                         # logs "ebreak bot.s:13 a0=1 fa0=..."
    li a0, 0
    ret

The trace keeps the first four log lines of each turn. A local match saves them in the replay, and npx @clunkyard/cli replay opens it in the viewer, whose trace panel shows each turn's lines beside what the robot sensed. Hosted, the same lines are in your robot's trace on the match page. An ebreak costs about 1,700 fuel; take them out when you are done.

Fuel: what a turn costs

Every instruction costs fuel, and so does every call; a turn has a budget, the same on every computer. The costs are fixed by kind:

Instruction Fuel
addi, add, mul and most integer instructions about 40
div, rem, loads and stores 53 to 58
fadd.d, fsub.d, fsqrt.d 85 to 105
fmul.d, fdiv.d, fcvt.w.d 95 to 156
fmin.d, fmax.d about 190
fmadd.d and the other fused instructions about 460
a cy_ call about 220, its 32-fuel call fee included

In Season 3 a RISC-V robot plays Standard at fuel tier 6: 1.79 billion fuel a turn, about 45 million instructions. The starter spends about 22,000 a turn. npx @clunkyard/cli match prints what yours spent.

Develop locally

Run the RISC-V player kit on Linux x86-64 with Node 24 or later, LLVM 17 or later with the RISC-V target, and ld.lld. Install clang and lld through your Linux distribution. Set CLUNKYARD_CLANG and CLUNKYARD_LD_LLD to their paths if they are outside PATH.

On macOS, Windows or ARM hosts, you can develop hosted in the Clunkyard workbench.

Then:

npx @clunkyard/cli new riscv my-robot
cd my-robot
npx @clunkyard/cli doctor            # finds clang with riscv32, and ld.lld
npx @clunkyard/cli build
npx @clunkyard/cli match 42 2d classic
npx @clunkyard/cli replay            # the replay, with your trace

The build assembles every .s file in the project, so you can split a robot into several. Put .include "clunkyard.inc" at the top of each; the build finds it in the SDK, so do not copy it into the project. An error names the file, line and column, as bot.s:4:5: error: unrecognized instruction mnemonic, did you mean: add, addi?. The linked program is kept as .clunkyard/build/bot.elf: llvm-objdump -d --no-show-raw-insn .clunkyard/build/bot.elf shows the instructions the assembler made, pseudo-instructions expanded, and their addresses, which is how to read clunkyard_turn+0x18 in a fault.

A robot is assembly source: the project may hold only text files, and the build refuses .incbin.

Develop hosted

Create a RISC-V robot on the site: the workbench opens bot.s with highlighting for the instructions, registers, labels and cy_ calls. Build shows the assembler's errors by file, line and column, and a practice match plays the robot against a house robot. With the MCP tools, build_robot returns the same diagnostics, and practice_match plays a match and matches shows its trace. npx @clunkyard/cli open ROBOT_ID clones a hosted robot to work on locally.

Starting from C

The machine runs any RV32IMFD code that follows ilp32d, so a compiler's assembly works too, and reading it is a good way to learn. Compile with the same target as the build, and keep the .s:

clang --target=riscv32-unknown-elf -march=rv32imfd -mabi=ilp32d -mno-relax -O2 -S steer.c -o steer.s

Things to keep in mind:

.include "clunkyard.inc"
.text
# int angle_diff(double target, double current, double *out) for C
.globl angle_diff
angle_diff:
    cy_angles_angle_diff
    ret

.globl clunkyard_turn
clunkyard_turn:
    li a0, 0
    ret

What this machine is

The official RISC-V test suites for RV32I, M, F and D pass on it, all but two RV32I tests that need what the machine leaves out by design: code that rewrites itself, and misaligned loads and stores. docs/design/riscv-assembly.md is the machine's design.

Reference

Every entry of the robot API 2.1.0 as a RISC-V robot calls it, with the macros clunkyard.inc defines. Each line gives the canonical signature (a property is read like a field; a call takes the arguments shown; "or none" may be absent), the macro and its registers, and what it gives. &name is an address you pass: of a record the call reads, or of room for what it writes. Each call returns its status in a0: CY_OK, CY_NONE when an "or none" result is absent (the memory is left as it was), CY_SHORT when a list or text does not fit (the count or length says how much is needed), or a negative error. Text is an address and a length in bytes, not NUL-terminated; a list is an address, a capacity in records and the address of a count.

match

clock

arena

me

battery

drive

gun

scanner

sensors

tracker

score

drone

angles

status

debug

raw

session

Records

Each record's size and each field's offset from the record's start, in bytes. A double is 8 bytes, and a whole number, flag or enum a 4-byte word; _SIZE after a field's name gives its size too.

Enums

Download this page as Markdown