Metadata-Version: 2.1
Name: voyager-cpu
Version: 0.2
Summary: A simple 32-bit RISC-V CPU emulator
Project-URL: Homepage, https://github.com/cgshep/voyager-cpu
Project-URL: Bug Tracker, https://github.com/cgshep/voyager-cpu/issues
Author-email: Carlton Shepherd <carlton@linux.com>
License-Expression: MIT
License-File: LICENSE.md
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Assembly
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Emulators
Requires-Python: >=3.7
Requires-Dist: elftools>=0.29
Provides-Extra: tests
Requires-Dist: pytest>=7.0; extra == 'tests'
Description-Content-Type: text/markdown

# Voyager CPU

Voyager is a (very) experimental Python emulator of a 32-bit RISC-V core. It's built for research and education with simplicity in mind.

## Features

+ Supports the RV32I ISA using a non-pipelined CPU with a single-cycle instruction fetch, decode, and execution stage.
+ A simple virtual RAM into which test programs (ELF binaries) are loaded.
  -  The [official RISC-V ISA tests](https://github.com/riscv-software-src/riscv-tests/) can be used for this purpose (see below).
+ A basic REPL for viewing register and RAM contents, and executing the next N cycles.
+ MIT license.

## Build and Run

1. (Optional) Clone the pre-built RV32UI tests using:
```
git submodule init
git submodule update
```
The binaries will be placed under `tests/riscv-tests-prebuilt-binaries/`. Alternatively, you can build the [test suites from the official repo](https://github.com/riscv-software-src/riscv-tests/).

2. See the example in `src/voyagercpu/example.py`. You may run this directly using `python src/voyagercpu/example.py`.

3. Enjoy!

4. (Optional) Run the Voyager unit tests using `pytest`

## Todo

+ Add more tests, particularly at the execution stage.
+ Implement some ISA extensions, e.g. the M and C specifications.
+ Add pipelining and privileged mode.
+ Improve pretty printing.
+ Etc.

Please contribute!