RISC-V in ten minutes
The one page to keep open while you write a RISC-V robot. The RISC-V guide explains each part from the start.
A robot
.include "clunkyard.inc" # the calls and constants
.text
.globl clunkyard_turn # the machine calls it once a turn
clunkyard_turn:
li a0, 0 # 0: play on
ret
clunkyard_start, if there is one, runs once, before the first turn. Each
entry starts with every register zero but sp and ra; memory keeps its
contents for the match.
Registers
| Names | Use | After a call |
|---|---|---|
zero |
always 0 | |
ra |
return address | changed |
sp |
stack pointer, a multiple of 16 | kept |
a0–a7, fa0–fa7 |
arguments; results in a0, fa0 |
changed |
t0–t6, ft0–ft11 |
temporaries | changed |
s0–s11, fs0–fs11 |
saved: restore before you return | kept |
gp, tp |
reserved |
A cy_ call changes only a0 and a7.
The instructions a robot needs
| Want | Write |
|---|---|
| a number, an address, a copy | li t0, 42, la t0, LABEL, mv t1, t0 |
| integer arithmetic | add, sub, addi t0, t0, -1, mul, div, rem, neg |
| bits and shifts | and, or, xor, andi, slli, srli, srai |
| compare into 0 or 1 | slt, sltu, seqz, snez |
| load and store | lw/sw (word), lb/lbu/sb (byte), fld/fsd (double), as lw t1, 8(t0) |
| branch | beq, bne, blt, bge, bltu, bgeu, beqz, bnez, bltz, bgez |
| jump, call, return | j label, call label, ret, jr t0 |
| double arithmetic | fadd.d, fsub.d, fmul.d, fdiv.d, fsqrt.d, fmadd.d, fmin.d, fmax.d |
| double sign and copy | fmv.d, fneg.d, fabs.d |
| compare doubles into 0 or 1 | feq.d, flt.d, fle.d |
| convert | fcvt.d.w ft0, t0 (integer to double), fcvt.w.d t0, ft0, rtz (double to integer, truncated) |
| a trace point | ebreak: logs its line, a0 and fa0 |
Local labels: 1: is a label, 1b the nearest one backward, 1f forward.
# Count down from 10.
li t0, 10
1: addi t0, t0, -1
bnez t0, 1b
Memory
| Section | Holds | Access |
|---|---|---|
.text |
code | run only |
.rodata |
constants, such as .double 0.7 |
read only |
.data |
variables with a value, such as .word 5 |
read and write |
.bss |
variables that start at zero, such as .zero CY_CONTACT_SIZE |
read and write |
Align a double or a record with .balign 8, a word with .balign 4.
Addresses below 0x10000 fault; the stack is 128 KiB under 0x100000.
# A constant double, and a contact record to fill.
.include "clunkyard.inc"
.section .rodata
.balign 8
GAIN: .double 45.0
.section .bss
.balign 8
TARGET: .zero CY_CONTACT_SIZE
.text
.globl clunkyard_turn
clunkyard_turn:
la t0, GAIN
fld ft0, 0(t0) # ft0 = 45.0
la a0, TARGET
cy_sensors_nearest # a0 = CY_OK when a contact was written
li a0, 0
ret
A call
Arguments in a0, a1, ... (integers and addresses) and fa0, fa1, ...
(doubles), each in order, then the macro; the status in a0: CY_OK (0),
CY_NONE (1, nothing to say), negative for an error. A result is written
to the address you pass. A field is at its record's address plus its offset,
fld fa0, CY_CONTACT_BEARING(t0).
.include "clunkyard.inc"
.section .bss
.balign 8
NUMBER: .zero 8
.text
.globl clunkyard_turn
clunkyard_turn:
la a0, NUMBER
cy_me_heading # writes the heading at NUMBER
la t0, NUMBER
fld fa0, 0(t0)
cy_gun_aim_heading # takes it in fa0
li a0, 0
ret
Every call
Each call's macro and its registers: & is an address you pass, for a
record or room for the answer. The
guide's reference has what each one
does.
| Entry | Macro and registers |
|---|---|
match.mode |
cy_match_mode (a0 = &out) |
match.ruleset |
cy_match_ruleset (a0 = &out) |
match.control |
cy_match_control (a0 = &out) |
match.robots |
cy_match_robots (a0 = &out) |
match.is_3d |
cy_match_is_3d (a0 = &out) |
match.tick_rate |
cy_match_tick_rate (a0 = &out) |
match.max_ticks |
cy_match_max_ticks (a0 = &out) |
match.robot_id |
cy_robot_id (a0 = slot, a1 = &buf, a2 = capacity, a3 = &length) |
clock.tick |
cy_clock_tick (a0 = &out) |
clock.seconds |
cy_clock_seconds (a0 = &out) |
clock.remaining_ticks |
cy_clock_remaining_ticks (a0 = &out) |
arena.size |
cy_arena_size (a0 = &out) |
arena.gravity |
cy_arena_gravity (a0 = &out) |
arena.terrain_kind |
cy_arena_terrain_kind (a0 = &out) |
arena.ground_height |
cy_arena_ground_height (fa0 = x, fa1 = y, a0 = &out) |
me.health |
cy_me_health (a0 = &out) |
me.position |
cy_me_position (a0 = &out) |
me.velocity |
cy_me_velocity (a0 = &out) |
me.heading |
cy_me_heading (a0 = &out) |
me.pitch |
cy_me_pitch (a0 = &out) |
me.roll |
cy_me_roll (a0 = &out) |
me.angular_velocity |
cy_me_angular_velocity (a0 = &out) |
me.attitude |
cy_me_attitude (a0 = &out) |
me.grounded |
cy_me_grounded (a0 = &out) |
me.altitude |
cy_me_altitude (a0 = &out) |
me.wall_contact |
cy_me_wall_contact (a0 = &out) |
me.hurt |
cy_me_hurt (a0 = &out) |
me.applied |
cy_me_applied (a0 = &out) |
me.hull_mounts |
cy_me_hull_mounts (a0 = &out) |
me.to_mount |
cy_me_to_mount (fa0 = heading, fa1 = pitch, a0 = &out) |
me.from_mount |
cy_me_from_mount (fa0 = heading, fa1 = pitch, a0 = &out) |
me.mount_toward |
cy_me_mount_toward (a0 = &point, a1 = &out) |
battery.charge |
cy_battery_charge (a0 = &out) |
battery.capacity |
cy_battery_capacity (a0 = &out) |
battery.regen |
cy_battery_regen (a0 = &out) |
battery.sustainable_drive |
cy_battery_sustainable_drive (a0 = &out) |
battery.compute |
cy_battery_compute (a0 = &out) |
battery.drive_cost |
cy_battery_drive_cost (fa0 = fraction, a0 = &out) |
drive.hover_lift |
cy_drive_hover_lift (a0 = &out) |
drive.set |
cy_drive_throttle (fa0 = value), cy_drive_turn (fa0 = value), cy_drive_pitch_turn (fa0 = value) |
drive.forces |
cy_drive_thrust (fa0 = value), cy_drive_strafe (fa0 = value), cy_drive_lift (fa0 = value), cy_drive_yaw_torque (fa0 = value), cy_drive_pitch_torque (fa0 = value), cy_drive_roll_torque (fa0 = value), cy_drive_brake (fa0 = value) |
drive.get |
cy_drive_get_throttle (a0 = &out), cy_drive_get_turn (a0 = &out), cy_drive_get_pitch_turn (a0 = &out), cy_drive_get_thrust (a0 = &out), cy_drive_get_strafe (a0 = &out), cy_drive_get_lift (a0 = &out), cy_drive_get_yaw_torque (a0 = &out), cy_drive_get_pitch_torque (a0 = &out), cy_drive_get_roll_torque (a0 = &out), cy_drive_get_brake (a0 = &out) |
gun.aim_now |
cy_gun_aim_now (a0 = &out) |
gun.cooldown_ticks |
cy_gun_cooldown_ticks (a0 = &out) |
gun.spread |
cy_gun_spread (a0 = &out) |
gun.max_power |
cy_gun_max_power (a0 = &out) |
gun.damage_scale |
cy_gun_damage_scale (a0 = &out) |
gun.can_fire |
cy_gun_can_fire (fa0 = power, fa1 = reserve, a0 = &out) |
gun.shot_speed |
cy_gun_shot_speed (fa0 = power, a0 = &out) |
gun.shot_cost |
cy_gun_shot_cost (fa0 = power, a0 = &out) |
gun.reload_ticks |
cy_gun_reload_ticks (fa0 = power, a0 = &out) |
gun.shot_damage |
cy_gun_shot_damage (fa0 = power, a0 = &out) |
gun.power_for_speed |
cy_gun_power_for_speed (fa0 = speed, a0 = &out) |
gun.power_for_flight_time |
cy_gun_power_for_flight_time (fa0 = range, fa1 = seconds, a0 = &out) |
gun.lead |
cy_gun_lead (a0 = &contact, fa0 = power, a1 = &out) |
gun.lead_point |
cy_gun_lead_point (a0 = &position, a1 = &velocity, fa0 = power, a2 = &out) |
gun.aim |
cy_gun_aim_heading (fa0 = value), cy_gun_aim_pitch (fa0 = value) |
gun.fire |
cy_gun_fire, cy_gun_power (fa0 = value) |
gun.get |
cy_gun_get_aim_heading (a0 = &out), cy_gun_get_aim_pitch (a0 = &out), cy_gun_get_fire (a0 = &out), cy_gun_get_power (a0 = &out) |
scanner.last |
cy_scanner_last (a0 = &out) |
scanner.proximity_range |
cy_scanner_proximity_range (a0 = &out) |
scanner.reach |
cy_scanner_reach (fa0 = arc, a0 = &out) |
scanner.arc_for_reach |
cy_scanner_arc_for_reach (fa0 = range, a0 = &out) |
scanner.set |
cy_scanner_heading (fa0 = value), cy_scanner_arc (fa0 = value), cy_scanner_pitch (fa0 = value) |
scanner.is_on |
cy_scanner_is_on (a0 = &out) |
scanner.power |
cy_scanner_on (fa0 = value) |
scanner.get |
cy_scanner_get_heading (a0 = &out), cy_scanner_get_arc (a0 = &out), cy_scanner_get_pitch (a0 = &out), cy_scanner_get_on (a0 = &out) |
sensors.contacts |
cy_sensors_contacts (a0 = &out, a1 = capacity, a2 = &count) |
sensors.nearest |
cy_sensors_nearest (a0 = &out) |
sensors.cues |
cy_sensors_cues (a0 = &out, a1 = capacity, a2 = &count) |
sensors.contact |
cy_sensors_contact (a0 = slot, a1 = &out) |
sensors.position_of |
cy_sensors_position_of (a0 = &contact, a1 = &out) |
tracker.cue |
cy_tracker_cue (a0 = &out) |
tracker.nearest_bearing_rate |
cy_tracker_nearest_bearing_rate (a0 = &out) |
tracker.velocity |
cy_tracker_velocity (a0 = slot, a1 = &out) |
tracker.position |
cy_tracker_position (a0 = slot, a1 = &out) |
tracker.history |
cy_tracker_history (a0 = slot, a1 = &out, a2 = capacity, a3 = &count) |
tracker.last_seen |
cy_tracker_last_seen (a0 = slot, a1 = &out) |
tracker.configure |
cy_tracker_configure (fa0 = smoothing, a0 = forget_ticks, a1 = cue_ticks) |
nav.zone |
cy_nav_zone (a0 = &out) |
nav.zone.margin |
cy_nav_zone_margin (a0 = &point, a1 = &out) |
nav.zone.contains |
cy_nav_zone_contains (a0 = &point, fa0 = margin, a1 = &out) |
nav.zone.distance_from |
cy_nav_zone_distance_from (a0 = &point, a1 = &out) |
nav.storm |
cy_nav_storm (a0 = &out) |
nav.storm.margin |
cy_nav_storm_margin (a0 = &point, a1 = &out) |
nav.storm.contains |
cy_nav_storm_contains (a0 = &point, fa0 = margin, a1 = &out) |
nav.storm.distance_from |
cy_nav_storm_distance_from (a0 = &point, a1 = &out) |
nav.hill |
cy_nav_hill (a0 = &out) |
nav.hill.margin |
cy_nav_hill_margin (a0 = &point, a1 = &out) |
nav.hill.contains |
cy_nav_hill_contains (a0 = &point, fa0 = margin, a1 = &out) |
nav.hill.distance_from |
cy_nav_hill_distance_from (a0 = &point, a1 = &out) |
nav.wall_margin |
cy_nav_wall_margin (a0 = &out) |
nav.pickups |
cy_nav_pickups (a0 = &out, a1 = capacity, a2 = &count) |
nav.nearest_pickup |
cy_nav_nearest_pickup (a0 = kind, a1 = &out) |
nav.field_distance |
cy_nav_field_distance (a0 = &a, a1 = &b, a2 = &out) |
score.me |
cy_score_me (a0 = &out) |
score.best |
cy_score_best (a0 = &out) |
score.armour |
cy_score_armour (a0 = &out) |
drone.has |
cy_drone_has (a0 = &out) |
drone.ready |
cy_drone_ready (a0 = &out) |
drone.in_flight |
cy_drone_in_flight (a0 = &out) |
drone.launches_left |
cy_drone_launches_left (a0 = &out) |
drone.report |
cy_drone_report (a0 = &out) |
drone.sightings |
cy_drone_sightings (a0 = &out, a1 = capacity, a2 = &count) |
drone.launch |
cy_drone_launch, cy_drone_launch_heading (fa0 = value), cy_drone_launch_pitch (fa0 = value), cy_drone_launch_param (fa0 = value) |
drone.brief |
cy_drone_brief (a0 = index, fa0 = value) |
drone.get |
cy_drone_get_launch (a0 = &out), cy_drone_get_launch_heading (a0 = &out), cy_drone_get_launch_pitch (a0 = &out), cy_drone_get_launch_param (a0 = &out) |
angles.normalize |
cy_angles_normalize (fa0 = degrees, a0 = &out) |
angles.angle_diff |
cy_angles_angle_diff (fa0 = target, fa1 = current, a0 = &out) |
angles.bearing_to |
cy_angles_bearing_to (a0 = &from, a1 = &to, a2 = &out) |
angles.elevation_to |
cy_angles_elevation_to (a0 = &from, a1 = &to, a2 = &out) |
angles.direction |
cy_angles_direction (fa0 = heading, fa1 = pitch, a0 = &out) |
angles.distance |
cy_angles_distance (a0 = &a, a1 = &b, a2 = &out) |
angles.to_chassis |
cy_angles_to_chassis (fa0 = heading, fa1 = pitch, a0 = &attitude, a1 = &out) |
angles.from_chassis |
cy_angles_from_chassis (fa0 = heading, fa1 = pitch, a0 = &attitude, a1 = &out) |
angles.clamp |
cy_angles_clamp (fa0 = value, fa1 = low, fa2 = high, a0 = &out) |
status.set |
cy_status_text (a0 = &text, a1 = text_length), cy_status_value (fa0 = value) |
status.get |
cy_status_get_text (a0 = &buf, a1 = capacity, a2 = &length), cy_status_get_value (a0 = &out) |
debug.log |
cy_debug_log (a0 = &line, a1 = line_length) |
raw.number |
cy_raw_number (a0 = &path, a1 = path_length, a2 = &out) |
raw.text |
cy_raw_text (a0 = &path, a1 = path_length, a2 = &buf, a3 = capacity, a4 = &length) |
raw.has |
cy_raw_has (a0 = &path, a1 = path_length, a2 = &out) |
raw.flag |
cy_raw_flag (a0 = &path, a1 = path_length, a2 = &out) |
raw.count |
cy_raw_count (a0 = &path, a1 = path_length, a2 = &out) |
raw.line |
cy_raw_line (a0 = &buf, a1 = capacity, a2 = &length) |
raw.extra |
cy_raw_extra (a0 = &json, a1 = json_length) |
session.log |
cy_session_log (a0 = &line, a1 = line_length) |