<!-- Generated from sdk/riscv/cheatsheet.md and protocol/v2/api.json by protocol/v2/codegen/docs.js; do not edit. Run `make api`. -->
# RISC-V in ten minutes

The one page to keep open while you write a RISC-V robot. The
[RISC-V guide](https://clunkyard.com/sdk/riscv) explains each part from the start.

## A robot

```riscv
.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.

```riscv
    # 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`.

```riscv
# 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)`.

```riscv
.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](https://clunkyard.com/sdk/riscv#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) |
