FuturisticGadgetLab/sevastopol
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
╔═══════════════════════════════════════════════════════════════════════════╗
║ ║
║ .d88888b dP dP ║
║ 88. "' 88 88 ║
║ `Y88888b..d8888b.dP .dP.d8888b..d8888b.d8888P.d8888b.88d888b..d8888b.88 ║
║ `8b88ooood888 d8'88' `88Y8ooooo. 88 88' `8888' `8888' `8888 ║
║ d8' .8P88. ...88 .88' 88. .88 88 88 88. .8888. .8888. .8888 ║
║ Y88888P `88888P'8888P' `88888P8`88888P' dP `88888P'88Y888P'`88888P'dP ║
║ 88 ║
║ dP ║
║═══════════════════════════════════════════════════════════════════════════║
║ ║
║ RISC-V ISA Interpreter ║
║ ║
╚═══════════════════════════════════════════════════════════════════════════╝
Sevastopol is a user-mode RISC-V ISA interpreter. It executes
statically-linked RISC-V ELF binaries entirely in userspace, and it
deliberately avoids runtime code generation to reduce attack surface.
The design goal is correctness and simplicity over raw throughput.
Derived from bit-hack/riscv-vm and extended with RV64 support, a Makefile
build system, future FGL project integration, and ongoing performance improvements.
+==============================================================================+
| TABLE OF CONTENTS |
+==============================================================================+
1. Features
2. ISA Support
3. Build
4. Usage
5. Architecture
6. Syscall Emulation
7. Testing
8. Limitations
9. References
10. License
+==============================================================================+
| 1. FEATURES |
+==============================================================================+
* Full RV32I base integer instruction set
* RV32M multiply/divide extension
* RV32A atomic extension -- LR/SC, AMOSWAP, AMOADD, AMOAND, AMOOR,
AMOXOR, AMOMIN, AMOMAX, AMOMINU, AMOMAXU
* RV32F single-precision floating point
* RV64I base integer instruction set including word-width operations
(ADDIW, SLLIW, SRLIW, SRAIW, ADDW, SUBW, SLLW, SRLW, SRAW)
* RV64M multiply/divide including MULW, DIVW, DIVUW, REMW, REMUW
* RV64A doubleword atomic operations -- LR.D, SC.D, AMOSWAP.D through
AMOMAXU.D
* Zicsr (CSR read/write) and Zifencei (FENCE.I) extensions
* Interpreter with no dynamic code generation or executable memory allocation
* Sparse memory model backed by 4 KiB pages, allocated on first touch
* Host syscall emulation: write, read, open, close, fstat, brk, exit,
gettimeofday, lseek
* ELF loader for both 32-bit (RV32) and 64-bit (RV64) binaries
* Minimal public C API (riscv.h) -- suitable for embedding
* Sub-80 kB binary footprint (interpreter-only build)
* No CRT dependencies; builds with GCC or Clang on Linux and Windows
(via MinGW or MSVC)
+==============================================================================+
| 2. ISA SUPPORT |
+==============================================================================+
+---------------------+----------------------+
| Extension | Status |
+---------------------+----------------------+
| RV32I | Complete |
| RV32M | Complete |
| RV32F | Partial |
| RV32A | Complete |
| Zicsr | Complete |
| Zifencei | Complete |
| RV64I | Partial |
| RV64M | Partial |
| RV64A | Partial |
| RV64F / RV64D | None |
| C (compressed inst) | Partial |
+---------------------+----------------------+
* RV32 support is mature and passes tests.
* RV64 support is opt-in (build with RVVM_SUPPORT_RV64=1). When enabled,
the interpreter detects ELF class at load time and adjusts register
width and shift masks accordingly.
* C extension (compressed 16-bit instructions) is supported in the
interpreter. Build with RVVM_SUPPORT_RVC=1 to enable.
The decoder transparently expands all three C quadrants into their
32-bit equivalents. Binaries compiled with -march=rv32imac or
-march=rv64imac will work without modification.
* Supervisor-mode, hypervisor-mode, MMU, and paging are NOT implemented.
This is a user-mode only emulator with a flat memory model.
+==============================================================================+
| 3. BUILD |
+==============================================================================+
REQUIREMENTS
* GCC 9+ or Clang 12+
* GNU Make 4.0+
* riscv64-linux-gnu-gcc (for building RISC-V test binaries)
BUILD COMMANDS
# Clean build (interpreter only, RV32 ISA)
make clean && make
# Build with RV64 ISA support (interpreter)
make clean && make RVVM_SUPPORT_RV64=1
# Build with RVC compressed instruction support (interpreter)
make clean && make RVVM_SUPPORT_RVC=1
# Strict build (diagnostics mode)
# Uses -Wall -Wextra -pedantic -Werror to catch potential issues.
# The codebase is maintained to build cleanly under this mode.
# Static analysis via cppcheck is run separately before pushing.
make clean && make RVVM_STRICT=1
OUTPUT BINARIES
build/bin/riscv_vm Interpreter binary.
BUILD OPTIONS
+--------------------------+---------+------------------------------------+
| Option | Default | Description |
+--------------------------+---------+------------------------------------+
| RVVM_STRICT | 0 | -Wall -Wextra -pedantic -Werror |
| RVVM_SUPPORT_RV32M | 1 | RV32M multiply/divide |
| RVVM_SUPPORT_RV32F | 1 | RV32F single-precision float |
| RVVM_SUPPORT_RV32A | 1 | RV32A atomics (LR/SC, AMO) |
| RVVM_SUPPORT_RV32Zicsr | 1 | CSR read/write instructions |
| RVVM_SUPPORT_RV32Zifencei| 1 | FENCE.I instruction |
| RVVM_SUPPORT_RV64 | 0 | Enable RV64 ISA (widens registers, |
| | | adds word ops, 64-bit shifts) |
| RVVM_SUPPORT_RVC | 0 | Enable RVC compressed instructions |
+--------------------------+---------+------------------------------------+
+==============================================================================+
|| 4. USAGE |
+==============================================================================+
RUNNING A BINARY
./build/bin/riscv_vm myprogram.elf
RUNTIME OPTIONS
--help Display usage information
CROSS-COMPILING FOR THIS VM
# RV32 -- soft-float, statically linked, no CRT
riscv64-linux-gnu-gcc \
-march=rv32im \
-mabi=ilp32 \
-nostdlib -static \
-o prog.elf prog.c
# RV64 -- no compressed instructions, statically linked
riscv64-linux-gnu-gcc \
-march=rv64imafd \
-mabi=lp64d \
-nostdlib -static \
-o prog.elf prog.c
+==============================================================================+
| 5. ARCHITECTURE |
+==============================================================================+
5.1 OVERVIEW
The project is split into two layers:
Core (riscv_core/) -- ISA interpreter and instruction
decoder. Written in C11 with a minimal public
API defined in riscv.h.
Frontend (riscv_vm/) -- ELF loader, sparse memory map, host syscall
emulation. Written in C++14.
A standalone x64 code-generation library is no longer included;
execution is provided entirely by the interpreter in `decode.c`.
5.2 INTERPRETER (riscv.c)
The interpreter implements a straightforward fetch-decode-execute loop:
1. Fetch a 32-bit instruction word from memory via the callback-based
riscv_io_t interface.
2. Dispatch by opcode bits [6:2] to one of 32 handler functions
(op_load, op_op_imm, op_branch, etc.).
3. Execute the decoded operation on the architectural state (X
registers, PC, CSRs, FP registers).
4. Increment the cycle counter and repeat.
The interpreter serves as the default execution engine and the
reference implementation for correctness.
5.3 MEMORY MODEL
The frontend implements a sparse memory map:
* Backed by 4 KiB pages, allocated on first touch (demand paging).
* Addresses are passed as uint64_t values through the riscv_io_t
callback interface, supporting both 32-bit and 64-bit address spaces.
* Loads and stores are routed through function pointers, allowing the
frontend to intercept accesses for memory-mapped I/O, breakpoints,
or instrumentation without modifying the core.
* Misaligned access detection is performed in the core before calling
the memory callbacks.
5.4 ELF LOADER (elf.cpp)
* Reads both ELFCLASS32 and ELFCLASS64 ELF files.
* Detects the RISC-V machine type and ISA width from the ELF header.
* Walks the program header table, loading PT_LOAD segments into the
sparse memory map at their virtual addresses.
* Retrieves the entry point and sets the initial PC.
* Provides symbol table lookup for debugging (trace logs).
+==============================================================================+
| 6. SYSCALL EMULATION |
+==============================================================================+
The following host syscalls are emulated via the RISC-V ecall instruction:
+----------------+-----------+--------------------------------------------+
| Syscall | Status | Notes |
+----------------+-----------+--------------------------------------------+
| write | Complete | stdout (fd 1) and stderr (fd 2) |
| read | Complete | stdin (fd 0) |
| open | Partial | Sufficient for newlib-based programs |
| close | Partial | |
| fstat | Partial | |
| brk | Complete | Heap management via memory map |
| exit | Complete | Terminates the VM with the exit code |
| gettimeofday | Complete | Returns host wall-clock time |
| lseek | Complete | File seek |
+----------------+-----------+--------------------------------------------+
Frontend programs linked with newlib's RISC-V port and using standard
file I/O, heap allocation, and stdio should work without modification.
+==============================================================================+
| 7. TESTING |
+==============================================================================+
RUNNING TESTS
make test Run all test binaries through the interpreter
make test-helloworld Run a specific test
make test-multiply
make test-mandelbrot
make test-rsort
make test-towers
make test-puzzle
make test-pi
make test-smallpt
make test-dhrystone
make test-coremark
make test-linpack
make test-whetstone
The test timeout is configurable via TEST_TIMEOUT (default 15 seconds).
+==============================================================================+
| 8. LIMITATIONS |
+==============================================================================+
* COMPRESSED INSTRUCTIONS -- The C (compressed) extension is supported
in both the interpreter when built with RVVM_SUPPORT_RVC=1.
The decoder handles all three C quadrants and expands 16-bit
instructions to their 32-bit equivalents transparently.
32-bit instructions at 16-bit boundaries that cross a 4-byte word
boundary are handled via a two-word assembly in the instruction fetch.
Build RISC-V binaries with -march=rv32imac or -march=rv64imac.
* RV64 IS OPT-IN -- Build with RVVM_SUPPORT_RV64=1.
* NO MULTI-HART / SMP -- Single-threaded execution only.
* NO MMU -- Flat memory model; no virtual memory, page protection, or
supervisor mode.
+==============================================================================+
| 9. REFERENCES |
+==============================================================================+
* RISC-V Unprivileged ISA Specification
https://riscv.org/technical/specifications/
* Original riscv-vm project by bit-hack
https://github.com/bit-hack/riscv-vm
+==============================================================================+
| 10. LICENSE |
+==============================================================================+
The VM core and frontend are MIT-licensed as per the original riscv-vm.
Test binaries in tests/ are third-party works with their own licenses.
╔═════════════════════════════════════════════════════════════════════════════╗
║ ║
║ __.,,------.._ ║
║ ,'" _ _ "`. ║
║ /.__, ._ -=- _"` Y ║
║ (.____.-.` ""` j ║
║ VvvvvvV`.Y,. _.,-' , , , ║
║ Y ||, '"\ ,/ ,/ ./ ║
║ | ,' , `-..,'_,'/___,'/ ,'/ , ║
║ .. ,;,,',-'"\,' , . ' ' ""' '--,/ .. .. ║
║ ,'. `.`---' `, / , Y -=- ,' , ,. .`-..||_|| .. ║
║ff\\`. `._ /f ,'j j , ,' , , f , \=\ Y || ||`||_.. ║
║l` \` `.`."`-..,-' j /./ /, , / , / /l \ \=\l || `' || ||... ║
║ ` ` `-._ `-.,-/ ,' /`"/-/-/-/-"'''"`.`. `'.\--`'--..`'_`' || , ║
║ "`-_,', ,' f , / `._ ``._ , `-.`'// ,║
║ ,-"'' _.,-' l_,-'_,,' "`-._ . "`. /| `.'\ , |║
║ ,',.,-'" \=) ,`-. , `-'._`.V | \ // .. . /j║
║ |f\\ `._ )-."`. /| `.| | `.`-||-\\/ ║
║ l` \` "`._ "`--' j j' j `-`---' ║
║ ` ` "`,- ,'/ ,-'" / ║
║ ,'",__,-' /,, ,-' ║
║ Vvv' VVv' ║
║═════════════════════════════════════════════════════════════════════════════║
║ ║
║ Thanks for reading and have fun with it! ║
║ - Serexp, Futuristic Gadgets Laboratory ║
╚═════════════════════════════════════════════════════════════════════════════╝