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)

Download this page as Markdown