1 c791d5e8 2024-04-15 benni # 64-Bit Linux Userspace RISC-V Emulator
 2 452f8ae7 2024-04-07 benni This emulator allows you to run statically-compiled binaries for riscv64-unknown-linux-musl.
 3 452f8ae7 2024-04-07 benni The goal is to support most POSIX-compatible OS on most 64bit CPU architectures.
 4 9c836066 2024-04-07 benni 
 5 452f8ae7 2024-04-07 benni ## Instructions
 6 d67350d6 2024-07-06 benni 1. Build the toolchain:
 7 452f8ae7 2024-04-07 benni 
 8 d67350d6 2024-07-06 benni   $ cd tools && make -jN	# with N being the number of cores of your system
 9 452f8ae7 2024-04-07 benni 
10 d67350d6 2024-07-06 benni 2. Build the emulator itself and a few example programs:
11 452f8ae7 2024-04-07 benni 
12 d67350d6 2024-07-06 benni   $ cd .. && make
13 452f8ae7 2024-04-07 benni 
14 d67350d6 2024-07-06 benni 3. Build a additional example programs (optional):
15 452f8ae7 2024-04-07 benni 
16 d67350d6 2024-07-06 benni   $ cd tools && make extra
17 452f8ae7 2024-04-07 benni 
18 452f8ae7 2024-04-07 benni To run a test program do:
19 452f8ae7 2024-04-07 benni 
20 452f8ae7 2024-04-07 benni   $ make run
21 452f8ae7 2024-04-07 benni 
22 452f8ae7 2024-04-07 benni ## Supported Host Architectures
23 452f8ae7 2024-04-07 benni Due to design decisions, only 64bit archs can be supported:
24 452f8ae7 2024-04-07 benni 
25 452f8ae7 2024-04-07 benni - amd64
26 f3444ea0 2024-04-10 benni - arm64
27 b472dc4b 2024-06-10 benni - riscv64
28 e7b41912 2024-07-16 benni - powerpc64 (big-endian, some syscall support missing)
29 452f8ae7 2024-04-07 benni 
30 452f8ae7 2024-04-07 benni Note: Once I get more hardware, I can port it to other architectures.
31 452f8ae7 2024-04-07 benni 
32 452f8ae7 2024-04-07 benni ## Supported Host OSs
33 9c836066 2024-04-07 benni - OpenBSD
34 9c836066 2024-04-07 benni - FreeBSD
35 9c836066 2024-04-07 benni - NetBSD
36 9c836066 2024-04-07 benni - Linux
37 9c836066 2024-04-07 benni 
38 452f8ae7 2024-04-07 benni ## Non-standard Toolchain Dependencies
39 9c836066 2024-04-07 benni - gsed (GNU sed)
40 9c836066 2024-04-07 benni - gmake (GNU make)
41 94c1bcf2 2024-07-19 benni - texinfo
42 452f8ae7 2024-04-07 benni - sudo or doas (only for `make run`, see config.mk.*)
43 452f8ae7 2024-04-07 benni - wget or curl (only on Linux)
44 72b29795 2024-04-07 benni - clang (only on NetBSD, because the distribution gcc is too old)
45 14e6dfec 2024-07-16 benni - gcc (only on FreeBSD/powerpc64, because the distribution clang is broken)
46 452f8ae7 2024-04-07 benni 
47 452f8ae7 2024-04-07 benni ## Resources
48 452f8ae7 2024-04-07 benni - https://riscv.org/wp-content/uploads/2017/05/riscv-spec-v2.2.pdf
49 452f8ae7 2024-04-07 benni - https://five-embeddev.com/riscv-isa-manual/latest/instr-table.html
50 452f8ae7 2024-04-07 benni 
51 452f8ae7 2024-04-07 benni 
52 452f8ae7 2024-04-07 benni ## Bugs
53 452f8ae7 2024-04-07 benni This project is still very experimental and has bugs!
54 452f8ae7 2024-04-07 benni If you find one, please contact Benjamin Stürz <benni AT stuerz DOT xyz>.