rv

RISC-V CPU core written in ANSI C.

Features:

• RV32IMAC_Zicsr implementation with M-mode and S-mode
• Boots RISCV32 Linux
• Passes all supported tests in riscv-tests
• ~800 lines of code
• Doesn't use any integer types larger than 32 bits, even for multiplication
• Simple API (two required functions, plus one memory callback function that you provide)
• No memory allocations

API

/* Memory access callback: data is input/output, return RV_BAD on fault. */
typedef rv_res (*rv_bus_cb)(void *user, rv_u32 addr, rv_u8 *data, rv_u32 is_store, rv_u32 width);

/* Initialize CPU. You can call this again on `cpu` to reset it. */
void rv_init(rv *cpu, void *user, rv_bus_cb bus_cb);

/* Single-step CPU. Returns RV_E* on exception. */
rv_u32 rv_step(rv *cpu);

Usage

#include <stdio.h>
#include <string.h>

#include "rv.h"

#define RAM_BASE 0x80000000
#define RAM_SIZE 0x10000

rv_res bus_cb(void *user, rv_u32 addr, rv_u8 *data, rv_u32 is_store,
              rv_u32 width) {
  rv_u8 *mem = (rv_u8 *)user + addr - RAM_BASE;
  if (addr < RAM_BASE || addr + width >= RAM_BASE + RAM_SIZE)
    return RV_BAD;
  memcpy(is_store ? mem : data, is_store ? data : mem, width);
  return RV_OK;
}

rv_u32 program[2] = {
    /*            */             /* _start: */
    /* 0x80000000 */ 0x02A88893, /* add a7, a7, 42 */
    /* 0x80000004 */ 0x00000073  /* ecall */
};

int main(void) {
  rv_u8 mem[RAM_SIZE];
  rv cpu;
  rv_init(&cpu, (void *)mem, &bus_cb);
  memcpy((void *)mem, (void *)program, sizeof(program));
  while (rv_step(&cpu) != RV_EMECALL) {
  }
  printf("Environment call @ %08X: %u\n", cpu.csr.mepc, cpu.r[17]);
  return 0;
}

See tools/example/example.c.

Running Linux

This repository contains a machine emulator that can use rv to boot Linux. See tools/linux/README.md.

Targeting rv

Use riscv-gnu-toolchain with tools/link.ld.

Suggested GCC commandline:

riscv64-unknown-elf-gcc example.S -nostdlib -nostartfiles -Tlink.ld -march=rv32imac -mabi=ilp32 -o example.o -e _start -g -no-pie

To dump a binary starting at 0x80000000 that can be directly loaded by rv as in the above example:

riscv64-unknown-elf-objcopy -g -O binary example.o example.bin

Instruction List

Click an instruction to see its implementation in rv.c.

• addaddiamoadd.wamoand.wamomax.wamomaxu.wamomin.wamominu.w
• amoor.wamoswap.wamoxor.wandandiauipcbeqbge
• bgtubltbltubnec.addc.addic.addi16spc.and
• c.andic.beqzc.bnezc.ebreakc.jc.jalc.jalrc.jr
• c.lic.luic.lwc.lwspc.mvc.orc.sllic.srai
• c.srlic.subc.swc.swspc.xorcsrrccsrrcicsrrs
• csrrsicsrrwcsrrwidivdivuebreakecallfence
• fence.ijaljalrlblbulhlhulr.w
• luilwmretmulmulhmulhsumulhuor
• oriremremusbsc.wsfence.vmashsll
• sllisltsltisltiusltusrasraisret
• srlsrlisubswwfixorxori

FAQ

Spaghetti code!

• rv was written in a way that takes maximal advantage of RISCV's instruction orthogonality.
• rv also tries to strike a good balance between conciseness and readability.
• Of course, being able to read this code at all requires intimate prior knowledge of the ISA encoding.

No switch statements!

• C only allows constant expressions in switch statements. In addition to an abundance of break statements using these would result in more bloated code in the author's opinion. As it turns out, you are actually free to reimplement this code with switch statements. See LICENSE.txt.

Not useful!

• Ok

Slow!

• Ok

Caveats

• Written in C89.
• Not actually written in C89, since it uses external names longer than 6 characters.
• Doesn't use any integer types larger than 32 bits, even for multiplication, because it's written in C89.
• Assumes width of integer types in a way that's not completely compliant with C89/99. Fix for this is coming soon, I'm working on a watertight <stdint.h> for C89.
• Written in C89.