Implementing a basic RISC-V emulator, aimed at being easily extendable. Check out the docs at readthedocs or riscemu.datenvorr.at.
This emulator contains:
- RISC-V Assembly parser
- RISC-V Assembly loader
- Emulation for most parts of the basic RISC-V instruction set and the M and A extensions
- Naive memory emulator
- Basic implementation of some syscalls
- A debugging environment
$ pip install riscemuA couple of basic assembly programs are provided inside examples/, such as hello-world.asm.
You can run it by typing python -m riscemu examples/hello-world.asm. It will produce output similar to:
[MMU] Successfully loaded: LoadedExecutable[examples/hello-world.asm](base=0x00000100, size=24bytes, sections=data text, run_ptr=0x00000110)
[CPU] Started running from 0x00000110 (examples/hello-world.asm)
Hello world
Program exited with code 0
The read syscall defaults to readline behaviour. Reading "true chunks" (ignoring newlines) is currently not supported.
See the docs on assembly for more detail on how to write assembly code for this emulator. See the list of implemented syscalls for more details on how to syscall.
Currently, symbols (such as main or loop) are looked-up at runtime. This allows for better debugging, I believe.
Basic IO should work, as open, read, write and close are supported for stdin/stdout/stderr and even arbitrary file paths (if enabled)
When trying to run an assembly program, the emulator first tries to find a symbol named _start, then a symbol named main. if both
symbols were not found in the file, it simply starts at the beginning of the .text segment.
Current CLI is not final, options may change frequently until a stable version is reached
This is how the interface is used:
usage: riscemu [-h] [--options OPTIONS] [--syscall-opts SYSCALL_OPTS] [--instruction-sets INSTRUCTION_SETS] [--stack_size stack-size] file.asm [file.asm ...]
OPTIONS and SYSCALL_OPTIONS is a list of comma-separated flags that will be enabled
--options OPTIONS: (-o)
disable_debug Disable the ebreak and sbreak instructions
no_syscall_symbols Don't make syscall symbols globally available
fail_on_ex Do not launch an interactive debugger when the CPU loop catches an exception
add_accept_imm accept "add rd, rs, imm" instructions, even though they are not standard
--syscall-opts SYSCALL_OPTS: (-so)
Options to control syscall behaviour
fs_access Allow access to the filesystem
disable_io Disallow reading/writing from stdin/stdout/stderr
--instruction-sets INSTRUCTION_SETS: (-is)
A list of comma separated instruction sets you want to load:
Currently implemented: RV32I, RV32M
If multiple files are specified, all are loaded into memory, but only the last one is executed. This might be improved
later, maybe the _init section of each binary is executed before the main loop starts?
If stack_size is greater than zero, a stack is allocated and initialized, with the sp register pointing to the end of the stack.
Debugging is done using the ebreak (formerly sbreak) instruction, which will launch a debugging session if encountered.
See docs/debugging.md for more info.
Check out the documentation.
To generate your local documentation, first install everything in sphinx-docs/requirements.txt. Then run ./generate-docs.sh, which will
generate and make all doc files for you. Finally, you can open the docs locall by running open sphinx-docs/build/html/index.html.
- RISC-V Programmers Handbook: https://github.com/riscv-non-isa/riscv-asm-manual/blob/master/riscv-asm.md
- Pseudo ops: https://www.codetd.com/article/8981522
- detailed instruction definition: https://msyksphinz-self.github.io/riscv-isadoc/html/rvi.html#add
- RISC-V reference card: https://www.cl.cam.ac.uk/teaching/1617/ECAD+Arch/files/docs/RISCVGreenCardv8-20151013.pdf
- Correctly handle 12 and 20 bit immediate (currently not limited to bits at all)
- Add a cycle limit to the options and CPU to catch infinite loops
- Move away from
printand uselogging.loggerinstead - Writer proper tests